winston-loggly-bulk

A Loggly transport for winston.

A client implementation for Loggly in node.js. Check out Loggly's Node logging documentation for more.

Looking for [email protected] documentation?

Please note that the documentation below is for [email protected]. Read the [email protected] documentation.

Usage

  var winston = require('winston');

  //
  // Requiring `winston-loggly-bulk` will expose
  // `winston.transports.Loggly`
  //
  var {Loggly} = require('winston-loggly-bulk');

  winston.add(new Loggly({options}));

The Loggly transport is based on Nodejitsu's node-loggly implementation of the Loggly API. If you haven't heard of Loggly before, you should probably read their value proposition. The Loggly transport takes the following options. Either 'inputToken' or 'inputName' is required:

• level: Level of messages that this transport should log.
• subdomain: The subdomain of your Loggly account. [required]
• auth: The authentication information for your Loggly account. [required with inputName]
• inputName: The name of the input this instance should log to.
• inputToken: The input token of the input this instance should log to.
• json: If true, messages will be sent to Loggly as JSON.
• tags: An array of tags to send to loggly.
• isBulk: If true, sends messages using bulk url
• stripColors: Strip color codes from the logs before sending
• bufferOptions: Buffer options has two configurations.
  • size: Number of logs to be buffered.
  • retriesInMilliSeconds: Time in milliseconds to retry sending buffered logs.
• timestamp: If false, library will not include timestamp in log events.
  • Note: Library includes timestamp by default when we do not set timestamp option.
• networkErrorsOnConsole: The library keep track of different network errors and can log them to console. By default, logging errors on console is disabled and can be enabled easily by setting this parameter's value to true. If true, all the network errors will be logged to console.

Metadata: Logged in suggested Loggly format

Sample Working Code Snippet

var winston  = require('winston');
var {Loggly} = require('winston-loggly-bulk');

winston.add(new Loggly({
    token: "TOKEN",
    subdomain: "SUBDOMAIN",
    tags: ["Winston-NodeJS"],
    json: true
}));

winston.log('info', "Hello World from Node.js!");

Buffer Support

This library has buffer support during temporary network outage. User can configure size of buffer (no. of logs to be stored during network outage).

Add these below configuration in code snippet to override the default values of buffer option size and retriesInMilliSeconds.

bufferOptions: {
    size: 1000,
    retriesInMilliSeconds: 60 * 1000
}  

• Note: The default value of buffer size and retries in milliseconds are 500 and 30000 (30 seconds) respectively.

Flush logs and exit

Our library uses ajax requests to send logs to Loggly, and as ajax requests take time to complete, logs can be lost when process.exit() is called because it forces an immediate exit. To exit gracefully and ensure that the last logs get to Loggly, we created a function called flushLogsAndExit(). It waits for 10 seconds and then calls process.exit() itself. This allows enough time for the logs to be sent to Loggly.

Here is an example of how to use the method:

var winston = require('winston');
var {flushLogsAndExit} = require('winston-loggly-bulk');

winston.log("info", "Hello World from Node.js!");
flushLogsAndExit();
  

Motivation

tldr;?: To break the winston codebase into small modules that work together.

The winston codebase has been growing significantly with contributions and other logging transports. This is awesome. However, taking a ton of additional dependencies just to do something simple like logging to the Console and a File is overkill.

Installation

Installing npm (node package manager)

  $ curl http://npmjs.org/install.sh | sh

Installing winston-loggly-bulk

If you are running npm version 3 or higher then run the below command to setup the logging-

  $ npm install winston-loggly-bulk

If you are running npm version 2 or lower then run the below command to setup the logging-

  $ npm install winston-loggly-bulk winston

• Note: To check the currrent npm version run the below command-

  $ npm -v

Run Tests

All of the winston tests are written in vows, and cover all of the use cases described above. You will need to add valid credentials for the various transports included to test/config.json before running tests:

  {
    "transports": {
      "loggly": {
        "subdomain": "your-subdomain",
        "inputToken": "really-long-token-you-got-from-loggly",
        "auth": {
          "username": "your-username",
          "password": "your-password"
        }
      }
    }
  }

Once you have valid configuration and credentials you can run tests with npm:

  npm test

Author: Charlie Robbins

Contributors: Loggly, Shweta Jain,