A Node.js wrapper for logentries.com APIs. This is a fork of the original node-entries that is being maintained.
The logentries module makes it very easy to log directly to your logentries.com account direct from Node.js! The logentries module does not depend on any non-core modules. You also need a logentries.com account - see getting started with logentries.com.
If you are looking for winston integration, please see winston-logentries.
npm install logentries
var logentries = require('logentries');
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"});
- simple API
- fully configurable
- also an EventEmitter
- fully tested
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 mylogger = require('logentries').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:
- log: capture each log event (maybe for your own archive)
- error: get notification of any errors in the logging system itself
The standard syslog log levels are used by default: debug, info, notice, warning, err, crit, alert, emerg.
For the API examples, assume the following lines of code at the top of your source code file:
var logentries = require('logentries')
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
- transport: optional; default is LogEntriesTransport; transport object
- levels: optional; default is syslog-style; custom log levels
- printerror: optional; default is true; print errors to STDERR with console.error
- timestamp: optional; default is true; autogenerate a timestamp
- usequotes: optional; default is false; add double quotes around every field
The token entry relates to your logentries.com configuration. The transport option allows you to provide an alternative transport implementation (see below).
By default the module will print errors to STDOUT to aid with debugging in a development context. To run this off, set the printerror option to false.
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 (in that order) to the log entry, and will be present in the logentries.com console.
The loglevel 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're naughty and use log levels like log and level, 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.
- 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);
});
This gives you the logline, a single string in the format:
"level" "ISODate" "entry"
- 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')
This module maintains an open HTTP connection to api.logentries.com, so that logging will be fast and efficient. If the connection breaks, it is automatically reestablished.
If you need to close the connection, call the end method. This primarily useful for unit testing to exit the test process. NOTE: if you submit further log entries after calling end, the connection will be reopened.
If you need finer grained control, then you will need to write your own transport object, or extend the existing one. See the lib/logentries.js file.
This module uses a transport object to perform the actual transfer of data to logentries.com. You provide your own customized transport object by using the transport configuration option.
If you are implementing your own transport object, you need to provide these interface methods:
- queue( queue ) : gives you an array to use as a queue, Array.shift items off
- consume() : process outstanding items in the queue by sending them to logentries.com
- end() : (optional) close connection to logentries.com
Take a look at the unit tests (in test folder) to see some simple implementations.
The unit tests use mocha, and are in the test folder.
npm test
The acceptance tests (these push actual data to the live logentries.com service) are simple node scripts, and are in the accept folder. Copy the accept/conf.js file to accept/conf.mine.js and add the token for your log file. Run directly:
node live.accept.js
Company site: logentries.com