fslog - a light node.js logging API

Similar to console.log, fslog logs message to both "files" and "stdout". The logs within the same day will be written in the same file by default. Also, fslog is able to automatically perform log rotation or remove expired logs (disabled by default).

Install with:

npm install fslog 

Usage

A simple example to use fslog.log.

    // Apply default settings of fslog
    var fslog = require("fslog")();

    // Use fslog.log like console.log
    // Use fslog.error like console.error
    // Support formatter
    var obj = {a:1};
    var arr = [1,'2',3];
    var num = 1;
    var str = '1'
    fslog.log(str,num,arr,obj);
    //fslog.error(str,num,arr,obj);
    //fslog.error('%s %d %j %j',str,num,arr,obj);

This will display:

1 1 [ 1, '2', 3 ] { a: 1 }

A log file with date-formatted name will be generated. For example, logs are written to the file "fslog-20150803.0" is generated. Its content will be:

1 1 [ 1, '2', 3 ] { a: 1 }

A simple example to use fslog.debuglog.

    // Apply user-specified settings of fslog
    // Log messages only when environment variable `NODE_DEBUG` contains `example`.
    // Automatically remove logs of seven days before.
    // Logs will be put under the directory `logs`.
    // The prefix of each log file will be `exampleLog`.
    var fslog = require("fslog")({
      section: 'example',
      retentionCheck: true, 
      retentionMinutes: 60*24*7,
      retentionRotationNum: 7,
      logdir: 'logs',
      logname: 'exampleLog'
    });

    // Use `fslog.debuglog` like `util.debuglog`
    // Do log messages only when environment variable `NODE_DEBUG` contains `example`. 
    fslog.debuglog(str,num,arr,obj);

API

log

Interface is similar to console.log. This writes logs to both "files" and "stdout". By default, this function asynchronously returns immediately, which does not wait for that writing process is completed. If synchronous mode is required, users can set sync to true in configuration. However, synchronous writing may significantly degrade performance.

error

Interface is similar to console.error. This writes logs to both "files" and "stderr". By default, this function asynchronously returns immediately, which does not wait for that writing process is completed. If synchronous mode is required, users can set sync to true in configuration. However, synchronous writing may significantly degrade performance.

debuglog

Interface is similar to util.debuglog. If environment variable "NODE_DEBUG" matches the specified section, it will write logs to files and stdout. If not, it is a no-op function. By default, this function asynchronously returns immediately, which does not wait for that writing process is completed. If synchronous mode is required, users can set sync to true in configuration. However, synchronous writing may significantly degrade performance.

destroy

This will destroy automatical log removal processes.

Configurations

Configurations can be passed by the following way:

   var config = {section:'example'};
   var fslog = require('fslog')(config);     

Available fields of configuration are listed as follows.

"section"

Specify a section for fslog.debuglog to conditionally writes logs and stdout. If this is not specified, fslog.debug is a no-op function.

"destination"

Specify the way to store logs. Three values are available to be set:

1. "file": output logs only to files.
2. "console": output logs only to console such as "stderr" or "stdout".
3. "both": output logs to both files and console.

Default: "both"

"logdir"

Specify the directory to store log files. If the directory does not exist, fslog will automatically create the directory. It is strongly suggested to specify your own proper directory to store and manage logs. DO NOT put important files (such as source codes) under the specified directory. Default: "fslog"

"logname"

Specify the naming of log files. For example, if logname is specified as "example", log files will be named with an incremental counter (example.x): "example.0", "example.1", "example.2", ... Otherwise, date-formatted names "fslog-YYYYMMDD-HH:MM.x" ("fslog-" is a prefix) are applied to write logs according to the retention granularity (per day by default). Default: (Use date-formatted string "fslog-YYYYMMDD-HH:MM.x").

"withtime"

If it is set to true, a timestamp will be embedded into the head of each log message when logging. Default: false.

"sync"

Specify the writing mode to file system. If this is set to true, every log is written to file system synchronously. If this is set to false, asynchronous writing is applied. Default: false.

Log Retenton Configuration

"retentionCheck"

If true, periodically remove expired logs. If false, logs will be kept forever. Default: false.

"retentionGranularity"

Specify the period which all the logs in this time range will be written in the same file. By default, all logs in the same day will be wriiten in the same file. Users can customize this granulariy by the following time units:

1. d: separated files by days. For example, "2d" means two days and "7d" means one week.
2. h: separated files by hours. For example, "3h" means three hours and "24h" means one day.
3. m: separated files by minutes. For example, "10m" means ten minutes and "60m" means one hour.

Note that the dated-formatted file names depend on the specified granularity. If the granularity is less than one hour, the corresponding file name will display minute information of logging time. Simiarly, if the granularity is less than one day but more than one hour, the file name shows only hour information but hides minutes. Default: "1d" (one log file per day)

"retentionMinutes"

Specify the lifetime to keep each log. Unit is in "minutes". This takes effect when retention is set to true. Default: 10080 (minutes) (= 7 days).

"retentionRotationNum"

Specify the number of logs kept simultaneously. This takes effect when retention is set to true. Default: 30

Note: If one of "retentionMinutes" and "retentionRotationNum" constraints violates, the log removing process will be performed to remove invalid logs.

"retentionCheckInterval"

Specify the interval in minutes to check expired logs under logdir. This takes effect when retention is set to true. Default: 1440 (minutes) (= 1 day).

An example of retention configuration:

{
   retentionCheck: true,
   retentionGranularity: '12h',
   retentionMinutes: 60*24*7,
   retentionRotationNum: 10,
   retentionCheckInterval: 120
}

The above configurations mean that every log file stores 12-hour data. The retention check is turned on and is performed every 120 minutes. Everytime it removes logs 7 days before or the oldest logs when the log number is more than 10.

Contributors

Bo-Han Wu ([email protected])

LICENSE - "MIT License"

Copyright (c) 2015 Bo-Han Wu ([email protected])

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.