ni-logging v1.0.3

NI Logging

Yet another JS message logging system.

Features

• Logs numbering
• Predefined log levels: DEBUG, INFO, WARN, ERROR, FATAL
• Custom log levels support
• Multiple log targets
• Logging errors
• Log configuration per target
• Filtering log entries

Code Example

Setup

const logConfigurationDev = [
    {
        target: new ConsoleTarget(),
        level: LogLevel.ALL
    }
];
Log.configuration = logConfigurationDev;

Usage

const logger = Log.getLogger(MyClass);

logger.debug('Debug message');
logger.info('Info message');
logger.warn('Warn message');
logger.error('Error message');
logger.fatal('Fatal error message');
logger.log(500, 'Custom level message');

try {
    saveDraft();
} catch (error) {
    logger.warn.withError(error, 'Saving draft failed');
}

try {
    login();
} catch (error) {
    let logEntry = logger.error.withError(error, 'Login failed');
    window.alert(`Log-in failed. See log #${logEntry.logNumber} for details`);
}

Installation

npm i ni-logging --save

Demo

Download demo from the Download section

or clone Demo project

API Reference

Log

Log object manages configuration, log targets and loggers. Use it to obtain a logger instance:

Log.getLogger(source, category)

Arguments:

• source (mandatory) is an object for which you create a Logger. Usually it's a class or constructor, but it can be any named function that would want to log messages or string.
• category (optional) is an additional parameter that can be used for filtering. It is intended to describe a functionality, group of functionalities (e.g. network, localization, settings) or a module of a larger platform (e.g. AccountsManager)

Example:

class Foo {
    constructor(parameter) {
        const logger = Log.getLogger(Foo);
        logger.info('Instance of Foo created with parameter', parameter);
    }
}

Set Log.configuration to overwrite default configuration.

Example:

let logCollection = [];

const logConfig = {
    DEV: [
        {
            target: new ConsoleTarget(),
            level: LogLevel.ALL,
            ignoredCategories: ['communication']
        },
        {
            target: new ArrayTarget(logCollection),
            level: LogLevel.ALL
        }
    ],
    UAT: [
        {
            target: new ConsoleTarget(),
            level: LogLevel.WARN
        },
        {
            target: new ArrayTarget(logCollection),
            level: LogLevel.ALL
        }
    ],
    PROD: [
        {
            target: new ConsoleTarget(),
            level: LogLevel.WARN
        },
        {
            target: new ArrayTarget(logCollection),
            level: LogLevel.INFO
        },
        {
            target: new ServiceTarget(logCollection),
            level: LogLevel.DEBUG
        }
    ]
}

Log.configuration = logConfig.DEV;

To keep your logs consistent, configuration should be set at application initialization and from that point should not be changed.

Configuration entry description:

• target - log target to send messages to. ni-logger is shipped with ConsoleTarget and ArrayTarget. See Creating custom log target to find out how to create your own one.
• level - specifies min message level - all messages with specified level or higher will be logged to given target. See LogLevel for the list of predefined levels.
• ignoredSources - array of filters. All messages sent by Logger with a source that matches any of the filters will be ignored.
• ignoredCategories - Same rule as for ignoredSources but for categories.
• acceptedSources - array of filters. Contains exceptions from the ignoredSources filters.
• acceptedCategories - array of filters. Contains exceptions from the ignoredCategories filters.

Filters

Filter can be

• string - test
• RegExp - new RegExp('^test')
• function - function (value) { return value.length > 10; }

LogLevel

Log level is a number.

LogLevel object provides predefined log levels:

• LogLevel.ALL = 0
• LogLevel.DEBUG = 100
• LogLevel.INFO = 200
• LogLevel.WARN = 300
• LogLevel.ERROR = 400
• LogLevel.FATAL = 1000

Logger

Logger provides you with an interface to log messages with a given level.

Examples:

// First get an instance:
const logger = Log.getLogger(SampleSource);

logger.log(LogLevel.DEBUG, 'Message to be logged');

The above has same effect as:

logger.debug('Message to be logged');

logger.info('Message to be logged');

logger.warn('Message to be logged');

logger.error('Message to be logged');

logger.fatal('Message to be logged');

Every method from above can be extended to log an error:

logger.warn.withError(error, 'Message to be logged');

This is useful to log handled exceptions:

try {
    // [...]
} catch (error) {
    logger.warn.withError(error, 'Message to be logged');
}

Every Logger method return a log entry. This can be used to integrate logging with user notifications:

try {
    saveForm(content);
} catch (error) {
    let logEntry = logger.error.withError(error, 'Error while saving form', content);
    notificationMechanism.notify(`Could not save the form. See log number #${logEntry.logNumber} for technical details.`);
}

What's included?

• ArrayTarget
• ConsoleTarget
• PatternMessageFormatter
• StringMessageFormatter

Extending

You can easily extend package features:

• Creating custom log target
• Creating custom message formatter

Tests

Run tests with npm test

License

MIT