# ain2

> Syslog logging for node.js. Continuation of ain

Latest version **3.0.0** (published 2018-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install ain2
pnpm add ain2
yarn add ain2
bun add ain2
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2018-11-13 |
| First published | 2011-08-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 34.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | Alexander Dorofeev |
| Maintainers | badunk, phuesler |

## Links

- npm: https://www.npmjs.com/package/ain2
- Repository: https://github.com/phuesler/ain
- Homepage: https://github.com/phuesler/ain#readme
- Issues: http://github.com/phuesler/ain/issues
- npm.io page: https://npm.io/package/ain2

## Dependencies (1)

- [unix-dgram](https://npm.io/package/unix-dgram.md) ^2.0.2

## Recent versions

- 3.0.0 (latest) — 2018-11-13
- 2.0.0 — 2016-05-06
- 1.5.3 — 2015-10-01
- 1.5.2 — 2015-02-23
- 1.5.1 — 2015-02-18
- 1.5.0 — 2015-01-12
- 1.4.0 — 2015-01-11
- 1.3.2 — 2014-02-13
- 1.3.1 — 2013-10-22
- 1.3.0 — 2013-10-22
- 1.2.1 — 2012-12-01
- 1.1.1 — 2012-11-24
- 1.1.0 — 2012-02-04
- 1.0.0 — 2012-01-02
- 0.2.1 — 2011-11-23
- … 4 more at https://npm.io/package/ain2/versions

## README

# ain*


Brain-free [syslog](http://en.wikipedia.org/wiki/Syslog)** logging for
[node.js](http://nodejs.org).

*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](https://npmjs.org/package/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 unix_dgram 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](http://www.faqs.org/rfcs/rfc3164.html) 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.](http://nodejs.org/api/dgram.html#dgram_socket_send_buf_offset_length_port_address_callback)
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](http://www.faqs.org/rfcs/rfc3164.html):

    #  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*.

# Development

    npm install
    npm test

---
_Source: https://npm.io/package/ain2 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._