A (winston compatible) Node.js module for logging directly to your logentries.com account.

( Note: this new le_node module is a significant rewrite, and may not be 100% compatible with the older node-logentries module. Let me know if you have any issues or suggestions. Thanks... )

    var logentries = require('le_node')

    var log = logentries.logger({
      token:'YOUR_TOKEN'
    })

    // level specific methods like 'info', 'debug', etc.
    log.info("I'm a Lumberjack and I'm OK")

    // generic log method, also accepts JSON entries
    log.log("debug", {sleep:"all night", work:"all day"})

    // use as a winston transport
    var winston = require('winston')
    log.winston( winston )

    // specify custom levels when using as winston transport
    log.winston( winston, { level: 'silly', levels: { silly: 0, info: 1, error: 2} })

• simple API
• fully configurable
• also an EventEmitter
• winston compatible

Core Methods:

• {debug,info,...}(log_entry) : log entry at debug,info,... level (configurable)
• log(level_name, log_entry) : log entry at level_name
• on(event_name, callback) : listen for logger events
• level(level_name) : discard entries below this level
• winston(winston, options) : register as a transport with winston
• end() : close connection to logentries.com (unsent logs remain queued)

npm install le_node

And in your code:

    var logentries = require('le_node')

Or clone the git repository: git clone git://github.com/logentries/le_node.git

The le_node module does not depend on any non-core modules.

You also need a logentries.com account - get started with logentries.com

This module sends your logging entries to the logentries.com service. You will need an account with this service for the module to work.

Once you have logentries.com account, you need just one configuration item to initialize a logging instance (you can create more than one):

• TOKEN: As supplied by Logentries when you create a logfile of source type Token TCP.

The module provides you with a set of logging methods that correspond to the standard syslog log levels. These are, in order of increasing severity:

• debug
• info
• notice
• warning
• err
• crit
• alert
• emerg

You can change these levels using the levels configuration option (see below).

Each level has a convenience method named after it, so you can say logger.debug(...) or logger.info(...), for example. There is also a general logging method, log, that takes the name of the log level as the first entry.

To create a logging instance, call the logger function of the module, passing any options as the first argument:

    var le = require('le_node');
    le.logger({ levels: { chill:0, meh:1, hmm:2, notgood:3, ohnoes:4, omgwtfbbq:5 } })

Each logger object is an instance of EventEmitter. You can listen for the following events:

• connect : notification of sucessful connection to Logentries service
• error : notification of any errors in the logging system itself
• log : capture each log event (maybe for your own archive)
• close : notification of socket Close event (disconnection from Logentries service, automatic reconnect will be attempted)
• end : notification of socket End event (usually after you invoke logger.end())

The standard syslog log levels are used by default: debug, info, notice, warning, err, crit , alert, emerg.
However, if installed as a winston transport (using the winston method), then the winston levels are used: silly, verbose, info, warn, debug, error.

For the API examples, assume the following lines of code at the top of your source code file:

    var logentries = require('le_node')
    var log = logentries.logger({ token:'YOUR_TOKEN' })

This gives you a standard log object.

You should really also read the logentries.com documentation so that you understand how logentries.com works: logentries.com User Guide

When you create a log object with the logger function on the module, you can supply the following options:

• token : required; logentries destination token uuid
• secure : optional; default is false; use tls for communication
• levels : optional; default is syslog-style; custom log levels
• timestamp : optional; default is true; autogenerate a timestamp

The token entry relates to your logentries.com configuration. The transport option allows you to provide an alternative transport implementation (see below).

The levels option lets you specify custom log levels. You provide these as a object, the property names of which are the log levels. The value of each log level should be an integer specifying its order. For example:

    { lowest:0, lower:1, middle:2, higher:3, highest:4 }

• entry : (required) log entry, can be string or JSON object

Submit a log entry. The entry data will be submitted to logentries.com. If a logging connection to logentries.com is not open, a connection will be opened, and any pending entries will be processed in order.

    log.info('buttered scones for tea')

The log level and an optional timestamp are prefixed to the log entry, and will be present in the logentries.com console.

The convenience methods are dynamically constructed from the configured list of logging levels, a method being constructed for each level, having the name of the level. If you use invalid log levels like 'log', 'level', 'on' or 'end', they will be ignored.

• level : (required) the name of the log level (must match one of the configured levels)
• entry : (required) log entry, can be string or JSON object

Submit a log entry, passing the name of the level programmatically. The dynamically constructed convenience methods, such as debug, delegate to this method internally.

    log.log('debug','press wild flowers')

A log entry will only be submitted if the log level is greater than or equal to the current log level setting of the logger. This allows you to drop noisy debugging logs from production environments.

If the only element passed to logger is a pure Javascript object, eg.

        log.info({ a:1, b:2, c:3 })

then the level name (and optional timestamp) will be added to the object rather than prepended as strings. This enables leWeb interface to present structured JSON, in place of simple text.

• event: (required) one of error or log
• callback: (required) callback function

This method is provided by the standard Node EventEmitter. Register callback functions to get notified of errors. The module cannot log errors itself, as it has nowhere to log them! Hosted environments may not provide writable disk access. Therefore, the module simply emits an error event that you can listen for. The module does also print errors to STDOUT by default, to help with debugging. Use the printerror configuration setting to control this (see above).

    log.on('error',function(err){
      console.log('hangs around.... In bars!? '+err )
    }

You may also need to gain access to the verbatim log lines. You can listen to the log event to do this:

    log.on('log',function(logline){
      console.log( logline )
    }

• name : (required) the name of the level

Set the current log level. All log entries below this level will be ignored. All log levels are given an integer rank when they are specified. The default rankings are:

    {
      debug     :0,
      info      :1,
      notice    :2,
      warning   :3,
      err       :4,
      crit      :5,
      alert     :6,
      emerg     :7
    }

For example, if you specify a level of warning, then log entries at levels debug, info, and notice will be dropped.

    log.level('warning')

• winston : (required) winston module
• options : (optional) set the winston level {level:'silly'}

The le_node module is fully compatible with the winston logging module. To log to logentries.com using winston, use the winston method. This takes care of all the transport object registration and set up for you. The winston log levels are automatically configured as the current log levels.

There is an optional second argument to specify some integration options. At present this only lets you set the winston log level, (which is info by default).

    var winston = require('winston')
    log.winston( winston, {level:'silly'} )

    // then use winston as normal
    winston.info('And I thought you were so rugged!')

With the winston API, you can specify a meta parameter to a log entry. The le_node module converts this to a JSON string and appends it to the log entry string.

This module maintains an open HTTP connection to api.logentries.com, so that logging will be fast and efficient.

If you need to close the connection, call the end method. This primarily useful for unit testing to exit the test process.

The unit tests use mocha, and are in the test folder.

    mocha test/le_node.test.js