ti-logger

A TI logging library for node.js and Node-Webkit

Motivation

ti-logger is a logging and tracing library. It supports logging to the console and/or to a file.

While there are many logging libraries, none support some of the special requirements ti-logger adresses. This include:

·          The ability to specify a source when logging.

·          The ability to specify for each source the logging-level

·          The ability to have different logging levels for the console and for the file.

·          The ability to configure the logger using a config-file

·          etc

Installation

npm install git@gitorious.design.ti.com:guicomposer-nw/guicomposer-nw/node-modules/ti-logger.git

Usage

The ti-logger module .

  var logger = require('ti-logger')();
 
  logger.error("this is a sample error');

Logging Levels

ti-logger define the following logging and tracing levels:

·          off

·          error

·          warn

·          info

·          trace

·          tracefiner

·          tracefinest

Using The Logging Levels

  var logger = require('ti-logger')();
 
  logger.error("my error messsage");
  logger.warn("my warning messsage");
  logger.info("my info messsage");
  logger.trace("my trace messsage");
  logger.tracefiner("my tracefiner messsage");
  logger.tracefinest("my tracefinest messsage");

configuration

ti-logger is very flexible and may be configured in several ways

·          via a configuration file

·          via a configuration Object

·          via a json String

·          via an API (limited scope)

The configuration file

The configuration file is located under: userhome/ti/appName

The config file name name is: log-config.json A typical content of the file will look like this

    {
        "fileLogger":
        {
            "json": false,
            "timestamp":true,
            "maxRollingFiles": 7,    
            "maxFileSize": 3145728,
            "levels": 
            {
                "defaultLevel": "trace",
                "module1":"warn",
                "module2":"trace"    
            }
        },
        "consoleLogger":
        {
            "json": false,
            "timestamp":true,
            "levels": 
            {
                "defaultLevel": "trace",
                "module1":"info",
                "module3":"trace"
            }
        }
    }

This file is loaded when the file require('ti-logger') is executed.

the configuration Object

When a configuration file may not be used, a configuration Object may be passed to the module as an arguments. In this case the default configuration file is ignored.

    var myConfig = 
    {
        "fileLogger":
        {
            "logDirectory":"c:/temp/mydirectory/logs",
            "logFilename":"myApp.log",
            "json": true,
            "timestamp":true,
            "maxRollingFiles": 5,    
            "maxFileSize": 3145728,
            "levels": 
            {
                "defaultLevel": "trace"
            }
        },
        "consoleLogger":
        {
            "json": false,
            "timestamp":false,
            "levels": 
            {
                "defaultLevel": "trace"
            }
        }
    };
 
    var logger = require('ti-logger')(myConfig);

the configuration Json

When a configuration file may not be used, a JSON configuration string may be passed to the module as an argument. In this case the default configuration file is ignored.

    var myConfigString = 
    "{ "fileLogger": { "json": true, "levels": { "defaultLevel": "warn"    } }, "consoleLogger": {    "json": false,"levels": {"defaultLevel": "off"}    }}";    
 
    var logger = require('ti-logger')(myConfigString);

the configuration parameters

·          logDirectory: The directory where log files will reside

·          logFilename: the name of the log file.

·          json: controls if the output is json based or not.

·          timestamp: controls if the log message will contain the date/time in an ISO format (example 2014-06-06T13:37:21.249Z)

·          maxRollingFiles: The maximum number of rolling log files. When a file reaches the maxFileSize, a new file is created.

·          maxFileSize: The maximum size in bytes of the log file.

·          defaultLevel: This is the default consoleLogger or fileLogger logging level. This may be any of: off, error, warn, info, trace, tracefiner, tracefinest

the configuration defaults

When a config parameters is not specified in the configuration, the following defaults are assumed:

·          logDirectory: /ti/appName/logs

·          logFilename: mainLog.log

·          json: true for fileLogger and false for the consoleLogger

·          timestamp: true for fileLogger and false* for the consoleLogger

·          maxRollingFiles: 5

·          maxFileSize: 3145728 (in bytes) or 3MB

·          defaultLevel: warn for fileLogger and off for the consoleLogger

Runtime Configuration changes

This is typically not required as we expect the configutaion to not change at runtime. However, if need arises, there are two ways to make changes to the configuration while the application is running:

By making changes to the configuration file:

When changes are made to the active configuration file and the file is then saved; the content of the file is automatically read and the changes are applied dynamically.

Configuration API

In the rare case where consoleLogger level or fileLevel needs to be programatically changed at runtime based on some criteria, an API has been provided to do that:

  var logger = require('ti-logger')(configurationObject);
  ....
  ....
  if(condition_1)
  {
    logger.setFileLoggerDefaultLevel('error');
    logger.setConsoleLoggerDefaultLevel('off');
  }
  else if(condition_2)
  {
    logger.setFileLoggerDefaultLevel('trace');
    logger.setConsoleLoggerDefaultLevel('tracefine');
  }
  else if(someOtherCondition)
  {
    logger.setFileLoggerDefaultLevel('tracefinest');
    logger.setFileLoggerDefaultLevel('tracefinest');
  }

Configuration precedence

Since configuration may be applied in different ways, this defines what takes precedence:

·          ConfigurationObject or JSON configuration

·          Configuration file under /ti/appname

·          Configuration File in the installation directory of the ti-logger module

The Source parameter

When logging a message, the developer may choose to include a source. The source may be a moduke name or a feature-name or anything else the developer wants it to be. In this case the API call would look like this:

  var logger = require('ti-logger')();
 
  logger.error("sourcename", "this is a sample error');

Specifying Source levels

The developer has the option of specifying a logging level in the configuration. The source logging level may be specified for the fileLogger, the consoleLogger or both.

    {
        "fileLogger":
        {
            "levels": 
            {
                "defaultLevel": "error",
                "source1":"warn",
                "source2":"trace"    
            }
        },
        "consoleLogger":
        {
            "levels": 
            {
                "defaultLevel": "off",
                "source1":"info",
                "source2":"warn",
                "source3":"trace"
            }
        }
    }