ain2

Brain-free syslog logging for node.js. Ain is written with full compatibility with node.js console module. It implements all console functions and formatting. Also ain supports UTF-8 (tested on Debian Testing/Sid). Ain can send messages by UDP to 127.0.0.1:514 or to the a unix socket; /dev/log on Linux and /var/run/syslog on Mac OS X. Unix socket support is possible if unix-dgram can be built and installed. In the Phoenician alphabet letter "ain" indicates eye. All examples tested under Ubuntu rsyslog. On other operating systems and logging daemons settings and paths may differ.

Installation

You can install ain as usual - by copy the "ain" directory in your ~/.node_modules or via npm

npm install ain2

Usage

Usage of ain is very similar to the node.js console. The following example demonstrates the replacement of the console: ```javascript var SysLogger = require('ain2'); var console = new SysLogger(); console.log('notice: %d', Date.now()); console.info('info'); console.error('error'); ``` After launch in /var/log/user you can see the following:

Dec  5 06:45:26 localhost ex.js[6041]: notice: 1291513526013

Dec  5 06:45:26 localhost ex.js[6041]: info

Dec  5 06:45:26 localhost ex.js[6041]: error

Note: you need to ensure syslog is listening on UDP port 514 for this example to work. On Ubuntu, for example, you would need to edit ``/etc/rsyslog.conf``, add/uncomment the following lines, and ensure rsyslog is restarted: ```

provides UDP syslog reception

$ModLoad imudp $UDPServerAddress 127.0.0.1 $UDPServerRun 514 ```

Singleton logger

If you want to have a singleton that points to the same object whenever you do a require, use the following: ```javascript require('ain2').getInstance(); ``` If you use this, please be beware of this: ```javascript require('ain2').getInstance() === require('ain2').getInstance(); => true ``` As opposed to: ```javascript var SysLogger = require('ain2'); new SysLogger() === new SysLogger(); => false ```

Changing destinations

By default ain sets following destinations:

• TAG - __filename

• Facility - user (1)

• HOSTNAME - localhost

• PORT - 514

• Transport - UDP

You can change them by passing in the params to the constructor or by using the set function. The set function is chainable. ```javascript var SysLogger = require('ain2'); var logger = new SysLogger({tag: 'node-test-app', facility: 'daemon', hostname: 'devhost', port: 3000}); logger.warn('some warning'); ``` ... and in /var/log/daemon.log:

Dec  5 07:08:58 devhost node-test-app[10045]: some warning

The set function takes one argument, a configuration object which can contain the following keys: tag - defaults to filename facility - defaults to user hostname - defaults to require('os').hostname() port - defaults to 514 transport - defaults to 'UDP' path - path to filesystem socket if using unixdgram transport messageComposer - a custom function to compose syslog messages All of these are optional. If you provide a hostname transport is automatically set to UDP tag and hostname arguments is just RFC 3164 TAG and HOSTNAME of your messages. facility is little more than just name. Refer to Section 4.1.1 of RFC 3164 it can be:

##  String  Description

-----------------------

0  kern    kernel messages

1  user    user-level messages

2  mail    mail system

3  daemon  system daemons

4  auth    security/authorization messages

5  syslog  messages generated internally by syslog daemon

6  lpr     line printer subsystem

7  news    network news subsystem

8  uucp    UUCP subsystem

16  local0  local use 0

17  local1  local use 1

18  local2  local use 2

19  local3  local use 3

20  local4  local use 4

21  local5  local use 5

22  local6  local use 6

23  local7  local use 7

You can set the facility by String or Number:

logger.set({tag: 'node-test-app', facility: 3});

logger.set({tag: 'node-test-app', facility: 'daemon'});

Also you can set TAG, Facility, HOSTNAME, PORT, and transport separately by setTag, setFacility, setHostname, setPort, setTransport and setMessageComposer functions. All of them are chainable too. You can get all destinations by these properties:

• tag TAG

• facility Numerical representation of RFC 3164 facility

• hostname HOSTNAME

• port PORT

Callbacks

Ain provides an optional callback after a message has been sent to the socket (udp and unix socket). The callback is passed up unaltered from node. Because ain supports a simplified printf format, the callback has to be the last parameter. ```javascript var SysLogger = require('ain2'); var console = new SysLogger(); console.info('info', function(err, bytes){ // callback received }); console.log('notice: %d', Date.now(), function(err, bytes){ // callback received }); ```

Custom message composer

```javascript var SysLogger = require('ain2'); var console = new SysLogger(); console.setMessageComposer(function(message, severity){

return new Buffer('<' + (this.facility * 8 + severity) + '>' +

this.getDate() + ' ' + '[' + process.pid + ']:' + message);

}); ``` The default implementation looks this: ```javascript SysLogger.prototype.composeSyslogMessage = function(message, severity) {

return new Buffer('<' + (this.facility * 8 + severity) + '>' +

this.getDate() + ' ' + this.hostname + ' ' +

this.tag + '[' + process.pid + ']:' + message);

} ```

Logging

As noticed before ain implements all console functions. Severity level is referenced to RFC 3164:

#  String   Description

-----------------------

0  emerg    Emergency: system is unusable

1  alert    Alert: action must be taken immediately

2  crit     Critical: critical conditions

3  err      Error: error conditions

4  warn     Warning: warning conditions

5  notice   Notice: normal but significant condition

6  info     Informational: informational messages

7  debug    Debug: debug-level messages

Ain console-like functions behaviour is fully compatible to node.js and logs messages with different severity levels:

• log - notice (5)

• info - info (6)

• warn - warn (4)

• error - err (3)

• dir - notice (5)

• time, timeEnd - notice (5)

• trace - err (3)

• assert - err (3)

To log a message with the desired severity level you can use the send function: ```javascript logger.send('message', 'alert'); ``` The send function takes two arguments: message and optional severity level. By default, the severity level is notice.

npm install

npm test