@alterior/logging

Overview

Provides a dependency-injected logger with support for pluggable listeners and log context tracking using Zone.js

Installation

npm install @alterior/logging

Usage

This module is intended to be used as part of an Alterior application. Several of the higher level first-party Alterior modules use this logger already, so it is a natural fit.

The module provides a Logger injectable when LoggingModule is imported into your Alterior application:

@Module({
    imports: [ LoggingModule ]
})
export class MyEntryModule { }

Once the module is imported, you can inject Logger into your services, controllers, tasks, etc:

import { Logger } from '@alterior/logging';
// ...

@Controller('/foo')
export class MyController {
    constructor(
        private logger : Logger
    ) {
    }

    @Get('/')
    get() {
        this.logger.info('Hello, world!');
    }
}

// [2019-03-05T00:12:44Z] [source="MyController"] info: Hello, world!

Subloggers (Source Labels)

You may wish to specifically mark logs which came from a particular class (or any other programmatic unit):

import { Logger } from '@alterior/logging';
// ...

@Injectable()
export class MyService {
    constructor(
        logger : Logger
    ) {
        this.logger = logger.withSource(this)
    }

    private logger : Logger;

    doSomething() {
        this.logger.info('Hello, world!');
    }
}

// [2019-03-05T00:12:44Z] [source="MyService"] info: Hello, world!

As you can see, withSource(object) will use the object's constructor name as the source label. You can also pass a string to set the source label to any string you wish.

Context tracking

This library also provides "context tracking" using Zone.js. When using context tracking, logs which occur inside a code block will be specially marked, even if the code is asynchronous or delayed.

logger.withContext({ myContextData: 123 }, `The data is 123`, () => {
    setTimeout(() => logger.info(`Hello, world!`), 1000);
});

// [2019-03-05T00:12:44Z] [context="The data is 123"] info: Hello, world!

This is the mechanism that allows @alterior/web-server and @alterior/tasks to include the current request trace inside logs generated by reusable services. This results in logs that are easier to follow, especially when there is heavy concurrency within a single log file (ie web servers, task runners):

[2019-03-05T00:12:44Z] [source="MyService" context="GET /foo | 1443c985-c4be-47f7-9e9c-941c21913def"] info: Hello, world!
[2019-03-05T00:12:44Z] [source="MyService" context="TaskWorker | MyBackgroundWorker"] info: Hello, world!

Configuration

To configure the module, import it into your entry module and specify options in the call to configure():

@Module({
    imports: [ LoggingModule.configure({ /* ... */ }) ]
})
export class MyEntryModule { }

listeners

"Listeners" are responsible for reporting logs in one way or another. By default a sensibly-configured ConsoleLogger is used. If you wish to customize the format, you'll need to specify your own instance of ConsoleLogger. If an empty set of listeners is specified, logs will effectively be dropped, and the logger itself becomes a no-op.

Log Objects

Log messages are passed to listeners as objects conforming to the LogMessage interface:

export interface LogMessage {
    message : string;
    context : any;
    contextLabel : string;
    sourceLabel : string;
    severity : LogSeverity;
    date : Date;
}

It is the responsibility of the listener to decide how to format these log message objects. Some listeners may not format the object at all (for instance: recording logs to a collection in an object store like MongoDB).

Log Formatting

Some built-in loggers use LogFormatter to handle transforming a log object into a string suitable for use on a screen, log file, etc. LogFormatter accepts a format string to determine how to transform the log message object into a string. Bare text is treated literally, and the fields of the LogMessage can be referenced by surrounding the name of the field with '%'. The default format for builtin listeners is:

%date% [source="%sourceLabel%" context="%contextLabel%"] %severity%: %message%

Available Listeners

new ConsoleLogger(formatString)

Outputs the log to the console using console.log() and friends. Accepts a format string suitable for use with LogFormatter.

new FileLogger(formatString, filename)

Writes logs to the specified file. Accepts a format string suitable for use with LogFormatter.

Execution Tracing

This library also provides @Trace(), a way to trace execution of one or more class methods automatically. When used outside of an Alterior application's execution context, tracing is always enabled. Within an Alterior app, you will have to specify tracing: true on the configuration for LoggingModule in order for @Trace() to be effective.

The log messages generated by @Trace() will be output using Logger.current. By default this will print to the console, but this can be changed by configuring LoggerModule in your application, or by simply constructing a new Logger and executing your code using logger.run().