@chax-at/log-sink v1.0.0

LogSink

LogSink is a simple logging package that allows logs to be sent to multiple destinations. These destinations are called "drains".

Usage

The package provides a singleton instance of LogSink as a default export:

import LogSink from '@chax-at/log-sink';

Before use the LogSink instance must be configured with at least one drain:

LogSink.registerDrain(new ConsoleLogDrain(), {
  enabled: true,
  minLevel: LOGGING_CONSOLE_MINLEVEL,
  maxLevel: LOGGING_CONSOLE_MAXLEVEL,
});

The singleton instance can then be imported in any file and used for logging:

import LogSink from '@chax-at/log-sink';

LogSink.info('This is an info message');

Advanced Logging

LogSink adheres to the syslog severity levels. Convenience methods for each level are provided:

LogSink.emergency('This is an emergency message');  // Level 0
LogSink.alert('This is an alert message');
LogSink.critical('This is a critical message');
LogSink.error('This is an error message');
LogSink.warning('This is a warning message');
LogSink.notice('This is a notice message');
LogSink.info('This is an info message');
LogSink.debug('This is a debug message');           // Level 7

In addition to a message, each of these methods take an optional tag, attribute object and timestamp:

enum LogTags {
  Database = 'database',
}

LogSink.info('This is an info message', LogTags.Database, { attr1: 'value1', attr2: 'value2' }, new Date());

If the log level is not known at compile time, the log method can be used:

LogSink.log(LogLevel.Info, 'This is an info message');

If needed, you can create additional LogSink instances:

import { LogSink } from '@chax-at/log-sink';
const logSink = new LogSink();

Drains

The package provides two built-in drains: ConsoleLogDrain and GelfLogDrain. New drains can be added by implementing the ILogDrain interface.

Drains are registered using the registerDrain method. Using minLevel and maxLevel, the severity levels can be filtered on each drain. Additionally, logs can be filtered using the filter method and transformed using the transform method.

LogSink.registerDrain(new ConsoleLogDrain(), {
  enabled: true,
  minLevel: LOGGING_CONSOLE_MINLEVEL,
  maxLevel: LOGGING_CONSOLE_MAXLEVEL,
  filter: (options: LogOptions) => {
    return options.tag === LogTags.Database;
  },
  transform: (options: LogOptions) => {
    return {
      ...options,
      message: options.message.toUpperCase(),
    };
  },
});

ConsoleLogDrain

The ConsoleLogDrain logs messages to the console. It can be configured to log attributes and use color.

new ConsoleLogDrain({ logAttributes: true, useColor: true });

GelfLogDrain

The GelfLogDrain logs messages to any GELF-capable server, such as Graylog. It uses @chax-at/gelf-client under the hood.

new GelfLogDrain(new SecureTCPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
    ca: GELF_SERVER_CA_CERT, // CA certificate string or buffer
    cert: GELF_CLIENT_CERT,  // Client certificate string or buffer
    key: GELF_CLIENT_KEY,    // CLient key string or buffer
}));

new GelfLogDrain(new TCPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
}));

new GelfLogDrain(new UDPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
    timeout: GELF_TIMEOUT,   // optional timeout (default 1000ms)
    protocol: GELF_PROTOCOL, // udp4 (default) or udp6
}));