meta2-logger

Simple logging library for NodeJS with support of facilities and multiple transports.

Logger has also first-class support for TypeScript and is fully documented.

Table of Contents:

• Features
• Installation
• Usage - TypeScript
• Usage - vanilla JS
• Facilities
• Setting log level
• Configuring Logging Targets
  • Console
  • File
  • JSON File
  • Memory
  • GrayLog
• Custom Logging Target
• Utility Functions
  • parseLogLevel
  • @Logging decorator
  • @LogMethodCall decorator
• Logging Stack Trace
• API Reference
• Development
• License

Features

Built-in transports:

• Console
• Text file
• JSON file
• Memory
• GrayLog

Log levels:

Library supports all of standard syslog levels.

• debug
• info
• notice
• warn
• error
• critical
• alert
• emergency

Other features:

• Facilities
• Meta-data
• Custom targets
• Colorized console output
• TypeScript decorators to simply enable logging on classes and methods
• Remote management server with UI and REST API provided by meta2-logger-server package

Installation

# Using NPM 
npm install meta2-logger
 
# To save as dependency 
npm install --save meta2-logger

Usage (TypeScript)

import {Logger, LOG_LEVEL, default as logger} from "meta2-logger";
 
// Use global logger
logger.info("From global logger");
 
// Or create new instance
const myLogger = new Logger({
    level: LOG_LEVEL.DEBUG
});
 
// Setup targets
logger.toConsole({
    level: LOG_LEVEL.INFO,
    timestamp: true,
    colorize: true
}).toFile("demo.log", {
    level: LOG_LEVEL.WARN,
    timestamp: true,
    facilities: [ "test" ]
}).toJsonFile("demo.json", {
    level: LOG_LEVEL.ERROR
}).toGrayLog({
    level: LOG_LEVEL.DEBUG,
    graylogHostname: "localhost"
    host: "myApp"
});
 
// Log some messages
logger.debug("Hello %s", "debug");
logger.info("Hello %s", "info");
logger.notice("Hello %s", "notice");
logger.warn("Hello %s", "warn"); // or logger.warning("Hello %s", "warn");
logger.error("Hello %s", "error");
logger.crit("Hello %s", "critical");
logger.alert("Hello %s", "alert");
logger.emerg("Hello %s", "emergency"); // or logger.panic("Hello %s", "emergency");
 
// Create facility
const facility = logger.facility("http", {
    level: LOG_LEVEL.INFO
});
 
facility.notice("Server started on port %d", 8080);
 
// Passing meta-data using object as first argument
facility.warn({ reqId: 123 }, "Bad request");

Usage (vanilla JS)

const Logger = require("meta2-logger");
 
// Accessing global logger instance
const logger = Logger.default;
 
// Or create new instance
const logger = new Logger.Logger();
 
// Setup targets
logger.toConsole({
    level: Logger.LOG_LEVEL.INFO,
    timestamp: true,
    colorize: true
}).toFile("demo.log", {
    level: Logger.LOG_LEVEL.WARN,
    timestamp: true,
    facilities: [ "test" ]
}).toJsonFile("demo.json", {
    level: Logger.LOG_LEVEL.ERROR
}).toGrayLog({
    level: Logger.LOG_LEVEL.DEBUG,
    graylogHostname: "localhost"
    host: "myApp"
});
 
// Log some messages
logger.debug("Hello %s", "debug");
logger.info("Hello %s", "info");
logger.notice("Hello %s", "notice");
logger.warn("Hello %s", "warn"); // or logger.warning("Hello %s", "warn");
logger.error("Hello %s", "error");
logger.crit("Hello %s", "critical");
logger.alert("Hello %s", "alert");
logger.emerg("Hello %s", "emergency"); // or logger.panic("Hello %s", "emergency");
 
// Create facility
const facility = logger.facility("http");
 
facility.notice("Server started on port %d", 8080);
 
// Passing meta-data using object as first argument
facility.warn({ reqId: 123 }, "Bad request");

Facilities

Logging facility provides a way to decouple logging based on their purpose.

Creating facility from logger:

import {default as logger, LOG_LEVEL} from "meta2-logger";
 
// Create facility from main logger - options are optional
const facility = logger.facility("facilityName", {
    level: LOG_LEVEL.INFO
});
 
// We can change facility log level later
facility.setLevel(LOG_LEVEL.NOTICE);
facility.getLevel(); // -> LOG_LEVEL.NOTICE
 
// Log to facility
facility.info("Message");
 
// We can get existing facility instance by calling facility method again
const facilityAgain = logger.facility("facilityName");
 
// We can get map of all registered facilities
logger.getAllFacilities(); // -> { facilityName: LoggerFacility }

Creating facility manually:

import {default as logger, LOG_LEVEL, LoggerFacility} from "meta2-logger";
 
// Create facility and pass logger as first argument, options are optional
const facility = new LoggerFacility(logger, "facilityName", {
    level: LOG_LEVEL.INFO
});
 
// Log to facility
facility.info("Message");

Setting log level

Log levels can be set on logger, facility and on targets.

Classes Logger, LoggerFacility and logging targets support setLevel and getLevel methods.

Example:

import {default as logger, LOG_LEVEL} from "meta2-logger";
 
logger.setLevel(LOG_LEVEL.INFO);
 
logger.debug("Message"); //Does not log
logger.warn("Message"); //Does log
 
logger.getLevel(); //Returns LOG_LEVEL.INFO;
 
// Changing log level on target(s)
logger.toConsole({
    level: LOG_LEVEL.NOTICE
});
 
logger.getTarget("__console__").setLevel(LOG_LEVEL.DEBUG);
logger.getTarget("__console__").getLevel(); // -> LOG_LEVEL.DEBUG
 
// Also works on LoggerFacility
const facility = logger.facility("http");
 
facility.setLevel(LOG_LEVEL.WARN);
facility.getLevel(); // -> LOG_LEVEL.WARN
 

Configuring Logging Targets

Logging target represents destination transport for log messages.

import {default as logger, ConsoleTarget, LOG_LEVEL} from "meta2-logger";
 
logger.to("uniqueLoggerId", new ConsoleTarget({
    level: Logger.LOG_LEVEL.INFO,
    timestamp: true,
    colorize: true
}));

See built-in targets below. Logging target class must implement ILoggerTarget interface.

Console Target

Prints log messages to stdout (console).

import {default as logger, ConsoleTarget, LOG_LEVEL} from "meta2-logger";
 
logger.toConsole({
    // Log level
    level: LOG_LEVEL.DEBUG,
 
    // Facilities - null to accept all facilities
    facilities: [ "http", "broker", "etc" ],
 
    // If to print time and date
    timestamp: true,
 
    // If to print with colors
    colorize: true
});
 
// Or
logger.to("myConsole", new ConsoleTarget(opts));

Sample output:

2018-01-10 14:24:30 warn: [http] (reqId=123) Bad request
2018-01-10 14:24:30 info: Something happend

eg.:
date time level: [facility] (meta=data) Formatted message

Notice: Method toConsole overrides previous console target settings. Use logger.to(...) method to define more targets.

File Target

Appends log messages to specified file.

Messages are formatted the same way as to the console.

File target can be set for multiple files with different configurations.

import {default as logger, FileTarget, LOG_LEVEL} from "meta2-logger";
 
logger.toFile("filename.log", {
    // Log level
    level: LOG_LEVEL.DEBUG,
 
    // Facilities - null to accept all facilities
    facilities: [ "http", "broker", "etc" ],
 
    // If to print time and date
    timestamp: true,
});
 
// Or
logger.to("myFile", new FileTarget("filename.log", opts));

Sample output:

2018-01-10 14:24:30 warn: [http] (reqId=123) Bad request
2018-01-10 14:24:30 info: Something happend

JSON File Target

Appends log messages to specified JSON file.

File target can be set for multiple files with different configurations.

import {default as logger, JsonFileTarget, LOG_LEVEL} from "meta2-logger";
 
logger.toJsonFile("filename.json", {
    // Log level
    level: LOG_LEVEL.DEBUG,
 
    // Facilities - null to accept all facilities
    facilities: [ "http", "broker", "etc" ]
});
 
// Or
logger.to("myJsonFile", new JsonFileTarget("filename.json", opts));

Sample output:

{},
{ timestamp: 1515557050.342, level: 5, facility: "http", msg: "Bad request", meta: { reqId: 123 } },
{ timestamp: 1515557086.342, level: 7, facility: null, msg: "Something happend", meta: {} }

Recommended way to parse JSON log file:

const fs = require("fs");
 
const logFile = fs.readFileSync("filename.json", { encoding: "utf-8" });
const logMessages = JSON.parse("[" + logFile + "]").slice(1);

Memory Target

Stores log messages in memory.

import {default as logger, MemoryTarget, LOG_LEVEL} from "meta2-logger";
 
logger.toMemory({
    // Log level
    level: LOG_LEVEL.DEBUG,
 
    // Facilities - null to accept all facilities
    facilities: [ "http", "broker", "etc" ],
 
    // How many messages to store, default 1000
    limit: 1000
});
 
// Get messages
logger.getTarget("__memory__").getMessages();
 
// Or
const memTarget = new MemoryTarget(opts);
 
logger.to("myMemory", memTarget);
 
memTarget.getMessages();

GrayLog Target

Sends log messages to GrayLog server using GELF protocol.

import {default as logger, GraylogTarget, LOG_LEVEL} from "meta2-logger";
 
logger.toGrayLog({
    // Log level
    level: LOG_LEVEL.DEBUG,
 
    // Facilities - null to accept all facilities
    facilities: [ "http", "broker", "etc" ],
 
    // GrayLog server port
    graylogPort: 12201,
 
    // GrayLog server hostname
    graylogHostname: "localhost",
 
    // Connection type, 'lan' or 'wan'
    connection: "lan",
 
    // Max chunk size for WAN type
    maxChunkSizeWan: 1420,
 
    // Max chunk size for LAN type
    maxChunkSizeLan: 8154,
 
    // Host (application) identifier
    host: "_unspecified_",
 
    // GELF protocol version
    version: "1.0",
 
    // Facility prefix string - is added before facility name
    facilityPrefix: "",
 
    // If to log gelf client debug messages to stdout
    debugGelfClient: false,
 
    // Additional static message fields
    additionalFields: { "myfield": "myValue" }
});
 
// Or
logger.to("myGrayLogTarget", new GraylogTarget(opts));

Notice: Message meta-data are added as additional fields.

Custom Logging Target

To create custom logging target define class which implements ILoggerTarget interface. Or extend class BaseTarget.

import * as util from "util";
 
import {
    LOG_LEVEL, ILoggerTarget, ILoggerMetaData, BaseTarget, IBaseTargetOptions,
    default as logger
} from "./interfaces";
 
export interface ISuchTargetOptions extends IBaseTargetOptions {
    soFunny?: boolean;
}
 
export class SuchTarget extends BaseTarget {
 
    protected soFunny: boolean:
 
    public constructor(options: ISuchTargetOptions) {
 
        super(options);
 
        this.soFunny = options.soFunny || false;
 
    }
 
    /**
     * Log message
     *
     * @param level Log level
     * @param facility Facility
     * @param args Message arguments
     * @param meta Meta-data
     */
    public log(level: LOG_LEVEL, facility: string, args: any, meta: ILoggerMetaData) {
 
        // Check such level
        if (level > this.level) return;
        if (this.facilities.length > 0 && this.facilities.indexOf(facility) < 0) return;
 
        // Format wow message
        const wowMessage = util.format.apply(this, args);
 
        // Create message parts
        const messageParts = [
            "Wow", Date.now(),
            "such", this.levelLabels[LOG_LEVEL.DEBUG].toUpperCase(),
            "many", facility,
            wowMessage,
            "plz",
            JSON.stringify(meta)
        ];
 
        if(this.soFunny)
            messageParts.push("so funny");
 
        // Write message
        this.write(level, facility, messageParts, meta);
 
    }
 
    /**
     * Write formatted log message
     *
     * @param level Log level
     * @param facility Facility
     * @param msg Formated message parts
     * @param meta Meta-data
     */
    protected write(level: LOG_LEVEL, facility: string, message: Array<string>, meta: ILoggerMetaData) {
 
        console.log("So scare", message.join(" "));
 
    }
 
}
 
// Use such target
logger.to("suchTarget", new SuchTarget({
    level: LOG_LEVEL.DEBUG,
    soFunny: true
}));

Utility Functions

parseLogLevel

This function parses log level from string to number. Is case insensitive.

Usage:

import {default as logger, parseLogLevel} from "meta2-logger";
 
logger.toConsole({
    level: parseLogLevel("criTIcal")
});

@Logging decorator

Decorator to configure and assign LoggerFacility instance to a class.

Note: decorators are experimental TypeScript feature.

Usage:

import {Logger, Logging, LoggerFacility, LOG_LEVEL} from "meta2-logger";
 
const myLogger = new Logger();
 
// Second argument can be omitted
@Logging("facilityName", {
    logger: myLogger, // When omitted default logger will be used
    level: LOG_LEVEL.DEBUG
})
class MyClass {
 
    public log: LoggerFacility;
 
    public doSomething(){
 
        this.log.info("Hello");
 
    }
 
}
 
const obj = new MyClass();
obj.doSomething(); // -> will log debug: [facilityName] Hello

@LogMethodCall decorator

Decorator to log every method call. When @Logging decorator is applied it's configuration will be used.

Note: decorators are experimental TypeScript feature.

Usage:

import {Logger, Logging, LogMethodCall, LoggerFacility, LOG_LEVEL} from "meta2-logger";
 
const myLogger = new Logger();
 
// Second argument can be omitted
@Logging("facilityName", {
    logger: myLogger, // When omitted default logger will be used
    level: LOG_LEVEL.DEBUG
})
class MyClass {
 
    public log: LoggerFacility;
 
    /*
     * Decorator arguments (all are optional):
     * - LOG_LEVEL
     * - If to capture arguments
     * - Message prefix
     */
    @LogMethodCall(LOG_LEVEL.DEBUG, true, "Hey")
    public doSomething(...args){
        return true;
    }
 
}
 
const obj = new MyClass();
obj.doSomething("hello", "world");

will log:

debug: [facilityName] (method=doSomething) (class=MyClass) Hey Method MyClass.doSomething called with arguments [ 'hello', 'world' ]
    at class_1.descriptor.value [as doSomething] (/path/to/app/node_modules/meta2-logger/dist/src/util.ts:90:38)
    at Logger.info (/path/to/app/node_modules/meta2-logger/dist/src/Logger.js:286:14)
    at Object.<anonymous> (/path/to/app/index.js:30:24)
    at Module._compile (module.js:571:32)
    at Object.Module._extensions..js (module.js:580:10)
    at Module.load (module.js:488:32)
    at tryModuleLoad (module.js:447:12)
    at Function.Module._load (module.js:439:3)
    at Module.runMain (module.js:605:10)

Logging Stack Trace (experimental)

Logger has built-in feature to capture stack trace for every log message. If enabled call stack will be available as trace meta value. Note that internal logger function calls are excluded.

Warning: Capturing of stack traces has a significant impact on performance and should be used only for temporary debugging.

This feature is currently experimental.

Also, note that this feature does not affect possibility to log stack trace by passing an error object as an argument to a log method - eg ... catch(err){ logger.error("Operation failed:", err); } will work always.

Following example:

import {default as logger} from "meta2-logger";
 
logger.enableTrace();
logger.toConsole();
 
logger.info("Hello!");
 
// To turn it off
logger.enableTrace(false);

will print to console:

info: hello
  >>
    at Logger.info (/path/to/app/node_modules/meta2-logger/dist/src/Logger.js:286:14)
    at Object.<anonymous> (/path/to/app/index.js:30:24)
    at Module._compile (module.js:571:32)
    at Object.Module._extensions..js (module.js:580:10)
    at Module.load (module.js:488:32)
    at tryModuleLoad (module.js:447:12)
    at Function.Module._load (module.js:439:3)
    at Module.runMain (module.js:605:10)

API Reference

class Logger {
    getLevel(): LOG_LEVEL;
    setLevel(level: LOG_LEVEL);
    log(level: LOG_LEBEL, ...args): void;
    debug(...args): void;
    info(...args): void;
    notice(...args): void;
    warn(...args): void;
    warning(...args): void;
    error(...args): void;
    crit(...args): void;
    alert(...args): void;
    emerg(...args): void;
    panic(...args): void;
    facility(name: string): LoggerFacility;
    getAllFacilities(): { [K: string]: LoggerFacility };
    to(id: string, target: ILoggerTarget): Logger;
    getAllTargets(): { [K: string]: ILoggerTarget };
    getTarget(id: string): ILoggerTarget|null;
    toConsole(options: IConsoleTargetOptions = {}): Logger;
    toFile(filename: string, options: IFileTargetOptions = {}): Logger;
    toJsonFile(filename: string, options: IFileTargetOptions = {}): Logger;
    toGrayLog(options: IGraylogTargetOptions): Logger;
    enableTrace(enabled: boolean);
    isTraceEnabled(): boolean;
 
    // Close all I/O and socket handles
    close();
}
 
class LoggerFacility {
    constructor(protected logger: Logger, protected prefix: string);
    getLevel(): LOG_LEVEL;
    setLevel(level: LOG_LEVEL);
    debug(...args): void;
    info(...args): void;
    notice(...args): void;
    warn(...args): void;
    warning(...args): void;
    error(...args): void;
    crit(...args): void;
    alert(...args): void;
    emerg(...args): void;
    panic(...args): void;
}
 
enum LOG_LEVEL {
    DEBUG = 7,
    INFO = 6,
    NOTICE = 5,
    WARN = 4,
    ERROR = 3,
    CRITICAL = 2,
    ALERT = 1,
    EMERGENCY = 0
}
 
interface ILogger {
    log(...args);
    debug(...args);
    info(...args);
    notice(...args);
    warn(...args);
    warning(...args);
    error(...args);
    crit(...args);
    alert(...args);
    emerg(...args);
    panic(...args);
    getLevel(): LOG_LEVEL;
    setLevel(level: LOG_LEVEL);
}
 
interface ILoggerMetaData {
    [ K: string ]: string|number|boolean|Date;
    [ K: number ]: string|number|boolean|Date;
}
 
interface ILoggerTarget {
    log: (level: LOG_LEVEL, facility: string, args: Array<any>, meta: ILoggerMetaData) => void;
    close: () => void;
    getLevel(): LOG_LEVEL;
    setLevel(level: LOG_LEVEL);
}
 
function parseLogLevel(level: string): LOG_LEVEL;

Development

# Install dependencies 
npm install
 
# Transpile TypeScript 
npm run build
 
# Run linter 
npm run lint
 
# Run tests 
npm test

License

This library is published under MIT license.

Copyright (c) 2017 - 2018 Jiri Hybek, [e-mail]