@jkm_15/winston-log2-gelf

winston-log2gelf

A Graylog2 or GELF transport for Winston@3.x. Supports HTTP(S) & TCP/TCP over TLS protocols.

If you're looking for the 1.x version supporting Winston < 3.x, check winston-log2gelf@1.9.1.

Installation

  $ npm install --save winston-log2gelf

Usage

  const winston = require('winston');
  const Log2gelf = require('winston-log2gelf');

  const logger = winston.createLogger({
    transports: [
        new winston.transports.Console({
            level: 'info',
            handleExceptions: true
        }),
        new Log2gelf({
            level: 'error',
            host: '192.168.0.15',
            port: 12201,
            protocol: 'tls'
        })
    ]
});

Note that if you wish to handle Exceptions, as Winston automatically exits after an exception, you have to disable the exit behaviour to let Log2gelf enough time to send the log across the network.

  const logger = winston.createLogger({
    exitOnError: false, // disable default winston exit
    transports: [
        new winston.transports.Console({
            level: 'info',
            handleExceptions: true
        }),
        new Log2gelf({
            level: 'error',
            host: '192.168.0.15',
            port: 12201,
            protocol: 'tls',
            handleExceptions: true, // handle exception within Log2gelf
            exitOnError: true, // exit after exception has been sent
            exitDelay: 1000 // leave Log2gelf 1sec to send the message
        })
    ]
});

If used in a script where the process has to naturally exit after its execution, the connection has to be closed (as a db connection would have to) if TCP socket is used. It should be done like so:

const log2gelf = logger.transports.find(transport => transport.name === 'log2gelf');
logger.end = log2gelf.end;

Options

• name: Transport name
• hostname: The name of this host (default: os.hostname())
• host: The GELF server address (default: 127.0.0.1)
• port: The GELF server port (default: 12201)
• protocol: Protocol used to send data (tcp, tls [TCP over TLS], http or https). (default: tcp)
• protocolOptions: See Overriding connection and request options.
• level: Level of messages this transport should log. See winston levels (default: info)
• silent: Boolean flag indicating whether to suppress output. (default: false)
• handleExceptions: Boolean flag, whether to handle uncaught exceptions. (default: false)
• exitOnError: Will exit after x ms (2 sec by default) if Winston exitOnError is set to false if an exception is caught
• exitDelay: Specify the exit delay in ms for exitOnError option. (default 2000)
• service: as facility is deprecated, service describes what kind of "service" this is (like MySQLd or Apache2). (default: nodejs)
• environment: the environment on which your service is running. (default: development)
• release: the version of your service (e.g. 1.0.0).
• disableMessageSanification: disable use of JSON.stringify over additional field to allow faster processing (default: false)
• legacyFormat: use the old full message encoding where the message object is passed through JSON.stringify (default: false)
• _foo: any underscore-prefixed custom option will be passed as is to the server.

Protocol-specific options

tcp and tls

• reconnect: Number of tcp reconnect attempts (default 0, 0 for none, -1 for infinite)
• wait: Milliseconds to wait between reconnect attempts (default 1000)
• keepAlive: Milliseconds after the last data packet received and the first keep alive probe (default 5000, 0 uses system default, less than 0 disable keep alive)
• timeout: Milliseconds after wich the socket times out if there was no activity over it

http and https

• keepAlive: Milliseconds after the last data packet received and the first keep alive probe (default 5000, 0 uses system default, less than 0 disable HTTP keep alive)

Overriding connection and request options

API change: prior to version 2.3.0, the host, port and rejectUnauthorized options were not overrideable by protocolOptions. They were also previously not applied when using the http or https protocol!

TCP connection and HTTP request specific options can be passed via protocolOptions. These options override the default options (for example, host and port), and are passed to the function making the request:

Protocol	API
tcp	net.socket.connect()
tls	tls.connect()
http	http.request()
https	https.request()

This can be used to, for example with the http and https protocol, include custom headers or change the path if the GELF HTTP input is behind a reverse proxy:

new Log2gelf({
    level: 'error',
    host: '192.168.0.15',
    port: 12202,
    protocol: 'http',
    protocolOptions: {
        path: '/gelf-input/gelf',
        headers: {
            'X-API-Key': 'secret-key'
        }
    }
})

Note: When using the http or https protocol, the Content-Length header is overwritten by winston-log2gelf to match the byte length of the message being sent and thus cannot be overridden with protocolOptions.

Debug information

The transport uses debug to print out some messages about it's internal functioning. To show them enable debug namespace winston-log2gelf.

Contributing

There's sure room for improvement, so feel free to hack around and submit PRs! Please just follow the style of the existing code, which is Airbnb's style with minor modifications.

To maintain things clear and visual, please follow the git commit template.