stdlog v0.0.8

stdlog

A node.js log utility that logs messages to stderr by default.

Overview

The stdlog package logs messages to stderr using five log levels: ERROR, WARN, INFO, DEBUG, and TRACE. An alternate stream or file can be used as well.

Installation

Add stdlog to your package.json dependencies:

"dependencies": {
    ...,
    "stdlog": "1.0.x"
}

Install the dependencies:

$ npm install

Usage

Require stdlog and create a log instance:

var stdlog = require('./stdlog');

// Create a log and set the log level using a constant.
var log = stdlog({
    level: stdlog.DEBUG
});

log.warn('This is a warning');
log.trace('This is not logged');

// Set the log level using a string.
log.setLevel('TRACE');
log.trace('Now it is logged');

Output:

2014-05-28T03:50:02.194Z WARN stdlog.test[14644]: This is a warning
2014-05-28T03:50:02.210Z TRACE stdlog.test[14644]: Now it is logged

Logging

Log Levels

There are five log levels. Each level has a numeric value and a string name. The numeric value and the string name can be used interchangeably. The name is case-insensitive when used in the setLevel method or when specified as the level property in an options object.

1. ERROR
2. WARN
3. INFO (this is the default log level)
4. DEBUG
5. TRACE

In addition, the log level having the numeric value zero (or the string name NONE) disables all logging.

Log Name

The log name comes from the package name of the application along with the module name of the parent module (the module calling require(stdlog). For example, the log name myapp.server is created from the package name (myapp) and the module requiring stdlog (server.js).

Log Methods

There are five corresponding log methods:

log.error(message [,args]);
log.warn(message [,args]);
log.info(message [,args]);
log.debug(message [,args]);
log.trace(message [,args]);

Each of these takes a message string (or an object, such as an Error) as the first parameter. The message can contain optional placeholders that are replaced by the values of any additional arguments.

• If the first argument is an object, then that object is converted to a string and becomes the error message.

• If the arguments following the message parameter are primitive values, then these values are accessed using numerical placeholders. For example, {0} is the first argument after the message parameter, {1} is the second argument after the message parameter, and so on.

• If the first argument following the message parameter is an array, then the numeric placeholders are array index values (e.g., {0}, {1}, etc.).

• If the first argument after the message argument is an object, then the placeholders are the object property names (e.g., {code}).

See Also: strformat

Configuration

There are three configuration options: level, output, and format. Each of these has a default value and can be set using an options property, a configuration method, or by setting an environment variable.

Setting the Log Level

The default log level is INFO. The log level can be set using the level, options property, the setLevel({Number|String}) method, or by setting the STDLOG_LEVEL environment variable.

The value of the argument or the environment variable can be either a number, the string representation of a number, or the case-insensitive log level name.

Note that the stdlog module exports the log levels as constants. Therefore, calling log.setLevel(stdlog.DEBUG) has the same result as calling log.setLevel('debug').

Setting the Log Output

The default log output is stderr. The log output can be set by using the output options property, the setOutput({Object|String}) method, or by setting the STDLOG_OUTPUT environment variable.

If the argument is an object, then is must provide a write function.

If the argument is a string, then the following rules apply:

1. The string stderr is interpreted as the stderr stream.
2. The string stdout is interpreted as the stdout stream.
3. Otherwise, the string is the pathname of a log file subject to the following:
   • A string beginning with a dot is resolved against the current working directory.
   • A string not beginning with a dot is resolved against the package or module directory of the parent module (the one requiring the stdlog package).

In the case of a log file, a file having the resolved name is created if it does not exist. Any intermediate directories (e.g., logs) are created using the mkdirp utility. Log messages are then appended to that file.

Setting the Log Format

The default log format is

{timestamp} {level} {name}[{pid}]: {message}

The log format can be set using the format options property, by calling the setFormat({String}) method, or by setting the STDLOG_FORMAT environment variable.

The following placeholders are available for use in the log format specification:

• {timestamp} - The ISO 8601 timestamp string using the UTC timezone.
• {level} - The log level name string (e.g., ERROR).
• {pid} - The numeric process id.
• {name} - The log name based on the package name and parent module name.
• {message} - The log message. Embedded newline characters are prefixed with a greater-than sign followed by a space so that multi-line messages are easily identified and parsed.

Setting all Log Options

Any or all of these options can be configured at once using the setOptions({Object}) method:

log.setOptions({
    level: 'trace',
    output: './server.log',
    format: '{level}: {message}'
});

Log Exceptions

An invalid value, such as an incorrect log level, results in an exception being thrown. Exceptions are thrown by the setOptions method as well as by any of the individual configuration methods.

Summary

Methods

setOptions({Object})
setLevel({Number|String}
setOutput({Object|String}
setFormat({String})

Motivations

The following three points motivated the creation and design of the stderr utility:

1. The console facility writes some messages to stdout and others to stderr. The UNIX convention is for stdout to be used for process output and stderr to be used for sideband information. The stdlog package logs all messages to stderr by default.

2. There are many other logging packages available. Some provide interesting color coding, others offer sophisticated interfaces to network log aggregators. This utility is a simple stream-based logger with the ability of appending messages to a log file.

3. The UNIX syslog facility offers more severity levels. This module is not intended for system logging so levels such as CRITICAL are of lesser value to a server operating as a guest process on an operating system. The five levels of ERROR, WARN, INFO, DEBUG, and TRACE offer a reasonable compromise.

Performance

The decision on whether or not to log a messages based on the current log level is made before any string formatting takes place. Therefore, log statements can be left in the code with minimal performance impact.

License

(The MIT License)

Copyright (c) 2014 Frank Hellwig

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.