pino-socket

pino-socket

Lead maintainer: jsumners

This module provides a "transport" for pino that simply forwards messages to an arbitrary socket. The socket can be UDPv4 or TCPv4. The module can echo the received logs or work silently.

You should install pino-socket globally for ease of use:

$ npm install --production -g pino-socket

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-socket',
  options: {
    address: '10.10.10.5',
    port: 5000,
    mode: 'tcp'
  }
})
pino(transport)

Options

Name	Description
address	The host address to connect to. Default: 127.0.0.1.
port	The host port to connect to. Default: 514.
unixsocket	The unix socket path for the destination. Default: ​.
mode	Either tcp or udp. Default: udp.
secure	Enable secure (TLS) connection. Default: false.
noverify	Allow connection to server with self-signed certificates. Default: false.
reconnect	Enable reconnecting to dropped TCP destinations. Default: false.
reconnectTries	Number of times to attempt reconnection before giving up. Default: Infinity.
onSocketClose	The callback when the socket is closed on TCP destinations. Default: (socketError) => socketError && process.stderr.write(socketError.message).
backoffStrategy	The backoff strategy to use on TCP destinations. The backoff strategy must implement the BackoffStrategy interface. Default: new FibonacciStrategy().
recovery	Enable a recovery mode when the TCP connection is lost which store data in a memory queue (FIFO) until the queue max size is reached or the TCP connection is restored. Default: false.
recoveryQueueMaxSize	The maximum size of items added to the queue. When reached, oldest items "First In" will be evicted to stay below this size. Default: 1024.
recoveryQueueSizeCalculation	Function used to calculate the size of stored items. The item is passed as the first argument and contains a data (Buffer) and encoding (String) attribute. Default: (item) => item.data.length + item.encoding.length.

Events

Name	Callback Signature	Description
open	(address: AddressInfo) => void	Emitted when the TCP or UDP connection is established.
error	(error: Error) => void	Emitted when an error occurs on the TCP or UDP socket.
close	(hadError: Boolean) => void	Emitted after the TCP or UDP socket is closed. The argument hadError is a boolean which says if the socket was closed due to a transmission error.

Usage as Pino Legacy Transport

Pino supports a legacy transport interface that is still supported by this module. Given an application foo that logs via pino, and a system that collects logs on port UDP 5000 on IP 10.10.10.5, you would use pino-socket like so:

$ node foo | pino-socket -a 10.10.10.5 -p 5000

OR

$ node foo | pino-socket -u /tmp/unix.sock

CLI Options

• --settings (-s): read settings from a JSON file (switches take precedence).
• --unixsocket (-u): the unix socket path for the destination. Default: ​.
• --address (-a): the address for the destination socket. Default: 127.0.0.1.
• --port (-p): the port for the destination socket. Default: 514.
• --mode (-m): either tcp or udp. Default: udp.
• --secure (-tls): enable secure (TLS) connection for TCP (only works with --mode=tcp).
• --noverify (-nv): allow connection to server with self-signed certificates (only works with --secure).
• --reconnect (-r): enable reconnecting to dropped TCP destinations. Default: off.
• --reconnectTries <n> (-t <n>): set number (<n>) of reconnect attempts before giving up. Default: infinite.
• --echo (-e): echo the received messages to stdout. Default: enabled.
• --no-echo (-ne): disable echoing received messages to stdout.
• --recovery: enable recovery mode for TCP (only works with --mode=tcp). Default: off.
• --recovery-queue-max-size <n>: maximum size of items (<n>) added to the recovery queue. Default: 1024.

Settings JSON File

The --settings switch can be used to specify a JSON file that contains a hash of settings for the application. A full settings file is:

{
  "address": "127.0.0.1",
  "port": 514,
  "mode": "tcp",
  "secure": false,
  "noverify": false,
  "reconnect": true,
  "reconnectTries": 20,
  "echo": false
}

Note that command line switches take precedence over settings in a settings file. For example, given the settings file:

{
  "address": "10.0.0.5",
  "port": 514
}

And the command line:

$ yes | pino-socket -s ./settings.json -p 1514

The connection will be made to address 10.0.0.5 on UDP port 1514.

License

MIT License