Home

Awesome

pino-syslog

Lead maintainer: jsumners

pino-syslog is a so called "transport" for the pino logger. pino-syslog receives pino logs from stdin and transforms them into RFC3164 or RFC5424 (syslog) formatted messages which are written to stdout. The default output format is RFC5424.

This transport does not send messages to a remote, or even local, syslog compatible server. It merely reformats the logs into syslog compatible strings. To send logs to a syslog server, use the pino-socket transport. For example:

$ node your-app.js | pino-syslog | pino-socket -a syslog.example.com

RFC3164

This RFC mandates that the maximum number of bytes that a syslog message may be is 1024. Thus, pino-syslog will do one of two things when this limit is exceeded:

  1. Output a JSON error log, with syslog header, that includes the original log's time and level properties, a originalSize property set to the number of bytes the original log message consumed, and a msg property set to "message exceeded syslog 1024 byte limit".
  2. Truncate the message to fit within the 1024 byte limit when the messageOnly configuration option is set to true.

This means you can lose data if your log messages are too large. If that is to be the case, you should investigate the includeProperties option to reduce your log size. But, really, you should investigate what it is you are logging.

RFC5424

This RFC does not limit the message size except to say that the receiver may impose a maximum. Thus, pino-syslog does not impose a length limit when conforming to this RFC. There are a couple of things to note, though:

  1. We do not currently support the structured data portion of the log header. This section of each log is always -.
  2. If the data to be logged includes req.id then it will be used as the message id portion of the log. For example, the data {req: {id: '1234'}} would have '1234' as the message id in the resulting formatted log.

These caveats may be configurable in a later version.

Example

Given the log:

{"pid":94473,"hostname":"MacBook-Pro-3","level":30,"msg":"hello world","time":1459529098958,"v":1}

pino-syslog will write out:

<134>1 2016-04-01T16:44:58Z MacBook-Pro-3 - 94473 - - {"pid":94473,"hostname":"MacBook-Pro-3","level":30,"msg":"hello world","time":1459529098958,"v":1}

Or, in RFC3164 mode:

<134>Apr  1 16:44:58 MacBook-Pro-3 none[94473]: {"pid":94473,"hostname":"MacBook-Pro-3","level":30,"msg":"hello world","time":1459529098958,"v":1}

Putting it all together:

$ echo '{"pid":94473,"hostname":"MacBook-Pro-3","level":30,"msg":"hello world","time":1459529098958,"v":1}' | node pino-syslog                                                       [s:0 l:8025]
<134>1 2016-04-01T16:44:58Z MacBook-Pro-3 - 94473 - - {"pid":94473,"hostname":"MacBook-Pro-3","level":30,"msg":"hello world","time":1459529098958,"v":1}

Usage as Pino Transport

You can use this module as a pino transport like so:

const pino = require('pino')
const transport = pino.transport({
  target: 'pino-syslog',
  level: 'info',
  options: {
    enablePipelining: false, // optional (default: true)
    destination: 1, // optional (default: stdout)
    ... // other options
  }
})
pino(transport)

The options object's properties are described below. There is some extra properties:

Pipelining

This feature is enabled by default and let you to submit the pino-syslog output to another destination at your choice, such as a socket using the pino-socket module:

const transport = pino.transport({
  pipeline: [
    {
      target: 'pino-syslog',
      level: 'info',
      options: {
        ... // other options
      }
    },
    {
      target: 'pino-socket',
      options: {
        mode: 'tcp',
        address: '127.0.0.1',
        port: 8001
      }
    }
  ]
})
pino(transport)

Usage as Pino Legacy Transport

Pino supports a legacy transport interface that is still supported by this module.

Install

You should install pino-syslog globally so that it can be used as a utility:

$ npm install --production -g pino-syslog

Configuration

pino-syslog supports configuration using option flags and/or via a JSON file. The option flags take precedence over the JSON configuration. The default options are:

{
  "modern": true,
  "appname": "none",
  "cee": false,
  "facility": 16,
  "includeProperties": [],
  "messageOnly": false,
  "tz": "UTC",
  "newline": false,
  "structuredData": "-",
  "sync": false
}

This also shows the full structure of a configuration file, which can be loaded using --config <path-to-file> (-c <path-to-file>).

Option flags

License

MIT License