README

Helix Log Framework

Logging framework used within the helix project.

Status

Development

Build

npm install

Test

npm test

Lint

npm run lint

Usage

const { info, error } = require('@adobe/helix-log');

info('This is an info level message ', { foo: 42 }, '; dumping any javascript variable like console.log is supported');
error('You can log exceptions like this', new Error('This is a problem'));

API Reference

Classes

The default constructor can be used to get the current point in time as a BigDate.

BunyanStreamInterface

Bunyan stream that can be used to forward any bunyan messages to helix log.

CoralogixLogger

Sends log messages to the coralogix logging service.

You can customize the host, application and subsystem per log message by specifying the appropriate fields.

LoggerBase

Can be used as a base class/helper for implementing loggers.

This will first apply the filter, drop the message if the level is too low or if the filter returned undefined and will then call the subclass provided this._logImpl function for final processing.

This also wraps the entire logging logic into a promise enabled/async error handler that will log any errors using the rootLogger.

FormattedLoggerBase

Can be used as a base class/helper for implementing loggers that require a formatter.

Will do the same processing as LoggerBase and in addition call the formatter before invoking _logImpl.

ConsoleLogger

Logger that is especially designed to be used in node.js Print's to stderr; Marks errors, warns & debug messages with a colored [ERROR]/... prefix.

Formatter MUST produce strings. Default formatter is messageFormatConsole.

MultiLogger

Simple logger that forwards all messages to the underlying loggers.

This maintains an es6 map called loggers. Consumers of this API are explicitly permitted to mutate this map or replace it all together in order to add, remove or alter logger.

FileLogger

Logger specifically designed for logging to unix file descriptors.

This logger is synchronous: It uses blocking syscalls and thus guarantees that all data is written even if process.exit() is called immediately after logging. For normal files this is not a problem as linux will never block when writing to files, for sockets, pipes and ttys this might block the process for a considerable time.

Formatter MUST produce strings. Default formatter is messageFormatTechnical.

MemLogger

Logs messages to an in-memory buffer.

Formatter can be anything; default just logs the messages as-is.

InterfaceBase

Can be used as a base class/helper for implementing logging interfaces.

This will make sure that all the required fields are set to their default value, apply the filter, drop the message if the level is too low or if the filter returned undefined and will then forward the message to the logger configured.

This also wraps the entire logging logic into a promise enabled/async error handler that will log any errors using the rootLogger.

SimpleInterface

The fields interface provides the ability to conveniently specify both a message and custom fields to the underlying logger.

Secret

Special wrapper that should be used to protect secret values.

Effectively this tries to hide the actual payload so that the secret has to be explicitly extracted before using it.

const mySecret = new Secret(42); // Create a secret
mySecret.value; // => 42; extract the value
mySecret.value = 64; // assign a new value

The secret can only be accessed through the .secret property in order to make sure that the access is not accidental; the secret property cannot be iterated over and the secret will not be leaked when converted to json or when printed.

WinstonTransportInterface

Winston transport that forwards any winston log messages to the specified helix-log logger.

const winston = require('winston');
const { WinstonTransportInterface } = require('helix-log');
const myWinsonLogger = W.createLogger({
transports: [new WinstonTransportInterface()]
});
// Will log 'Hello World' to the rootLogger with the fields:
// {category: 'testing'}.
myWinsonLogger.info('Hello World', category: 'testing');

Constants

rootLogger

The logger all other loggers attach to.

Must always contain a logger named 'default'; it is very much recommended that the default logger always be a console logger; this can serve as a good fallback in case other loggers fail.

JsonifyForLog

Trait used to serialize json objects to json. See jsonifyForLog.

Functions

eraseBunyanDefaultFields(fields) ⇒ Object

Remove the default fields emitted by buyan.

These fields are added by bunyan by default but are often not of much interest (like name, bunyanLevel, or v) or can be easily added again later for data based loggers where this information might be valuable (e.g. hostname, pid).

Use like this:

numericLogLevel(name) ⇒ number

This can be used to convert a string log level into it's numeric equivalent. More pressing log levels have lower numbers.

makeLogMessage([fields]) ⇒ Message

Supplies default values for all the required fields in log messages.

You may pass this a message that is just a string (as opposed to the usually required array of message components). The message will then automatically be wrapped in an array.

tryInspect(what, opts)

Wrapper around inspect that is extremely robust against errors during inspection.

Specifically designed to handle errors in toString() functions and custom inspect functions.

If any error is encountered a less informative string than a full inspect is returned and the error is logged using err().

serializeMessage(msg, opts) ⇒ string

Turns the message field into a string.

messageFormatSimple(fields) ⇒ MessageFormatter | string

Simple message format: Serializes the message and prefixes it with the log level.

This is used by the MemLogger by default for instance, because it is relatively easy to test with and contains no extra info.

messageFormatTechnical(fields) ⇒ MessageFormatter | string

Message format that includes extra information; prefixes each message with the time stamp and the log level.

This is used by FileLogger by default for instance because if you work with many log files you need that sort of info.

messageFormatConsole(fields) ⇒ MessageFormatter | string

Message format with coloring/formatting escape codes

Designed for use in terminals.

messageFormatJson(fields) ⇒ MessageFormatter | Object

Use jsonifyForLog to turn the fields into something that can be converted to json.

messageFormatJsonString(fields) ⇒ MessageFormatter | Object

Message format that produces & serialize json.

Really just an alias for JSON.stringify(messageFormatJson(fields)).

deriveLogger(logger, opts) ⇒ Logger

Helper function that creates a derived logger that is derived from a given logger, merging the given options. All the properties are shallow copied to the new logger With the exception of the defaultFields, where the defaultFields object itself is shallow-copied. Thus allowing to extend the default fields.

__handleLoggingExceptions(fields, logger, code) ⇒ Message

Helper to wrap any block of code and handle it's async & sync exceptions.

This will catch any exceptions/promise rejections and log them using the rootLogger.

fatal(...msg)

Log just a message to the rootLogger using the SimpleInterface.

Alias for new SimpleInterface().log(...msg).

This is not a drop in replacement for console.log, since this does not support string interpolation using %O/%f/..., but should cover most use cases.

messageFormatJsonStatic(fields) ⇒ Object

Message format used for comparing logs in tests.

Pretty much just messageFormatJson, but removes the time stamp because that is hard to compare since it is different each time...

If other highly variable fields are added in the future (e.g. id = uuidgen()) these shall be removed too.

recordLogs(opts, fn) ⇒ string

Record the log files with debug granularity while the given function is running.

While the logger is recording, all other loggers are disabled. If this is not your desired behaviour, you can use the MemLogger manually.

assertLogs(opts, fn, logs)

Assert that a piece of code produces a specific set of log messages.

recordAsyncLogs(opts, fn) ⇒ string

Async variant of recordLogs.

Note that using this is a bit dangerous as other async procedures may also emit log messages while this procedure is running

assertAsyncLogs(opts, fn, logs)

Async variant of assertLogs

Note that using this is a bit dangerous as other async procedures may also emit logs while this async procedure is running.

jsonifyForLog(what) ⇒ *

jsonify the given data using the JsonifyForLog trait.

Takes any javascript object and produces an object tree that only contains json compatible objects (objects, arrays, numbers, bools, strings and such).

This is a no-op if the input is already json compatible.

Note that this is specifically designed to serialize data for structured logging. This is NOT suitable for proper serialization of json; specifically this may loose information in cases where that makes sense.

Features a default converter for any exception/subclass of Error.

Typedefs

MessageFormatter ⇒ *

Most loggers take a message with log(), encode it and write it to some external resource.

E.g. most Loggers (like ConsoleLogger, FileLogger, ...) write to a text oriented resource, so the message needs to be converted to text. This is what the formatter is for.

Not all Loggers require text; some are field oriented (working with json compatible data), others like the MemLogger can handle arbitrary javascript objects, but still provide an optional formatter (in this case defaulted to the identity function – doing nothing) in case the user explicitly wishes to perform formatting.

Interfaces

Message

Internally helix log passe these messages around.

Messages are just plain objects with some conventions regarding their fields:

Logger

Loggers are used to write log message.

These receive a message via their log() method and forward the message to some external resource or other loggers in the case of MultiLogger.

Loggers MUST provide a log(message) method accepting log messages.

Loggers SHOULD provide a constructor that can accept options as the last argument new MyLogger(..args, { ...options });

Loggers MAY support any arguments or options in addition to the ones described here.

Loggers SHOULD NOT throw exceptions; instead they should log an error.

Loggers MUST use the optional fields & named options described in this interface either as specified here, or not at all.

Loggers SHOULD provide a named constructor option 'level' and associated field that can be used to limit logging to messages to those with a sufficiently high log level.

Loggers SHOULD provide a named constructor option 'filter' and associated field that can be used to transform messages arbitrarily. This option should default to the identity() function from ferrum. If the filter returns undefined the message MUST be discarded.

Loggers SHOULD provide a named constructor option 'defaultFields'; if they do support the property they MUST perform a shallow merge/setdefault into the message AFTER applying the filters.

If loggers send messages to some external resource not supporting the Message format, they SHOULD also provide an option 'formatter' and associated field that is used to produce the external format. This formatter SHOULD be set to a sane default.

Helix-log provides some built-in formatters e.g. for plain text, json and for consoles supporting ANSI escape sequences.

LoggingInterface

Helix-Log LoggingInterfaces take messages as defined by some external interface, convert them to the internal Message format and forward them to a logger.

Some use cases include:

Providing a Console.log/warn/error compatible interface
Providing winston or bunyan compatible logging API
Providing a backend for forwarding bunyan or winston logs to helix log
Receiving log messages over HTTP
SimpleInterface and SimpleInterface are used to provide the info("My", "Message") and info.fields("My", "Message", { cutsom: "fields" }) interfaces.

LoggingInterfaces SHOULD provide a constructor that can accept options as the last argument new MyInterface(..args, { ...options });

LoggingInterfaces MAY support any arguments or options in addition to the ones described here.a

LoggingInterfaces MUST use the optional fields & named options described in this LoggingInterface either as specified here, or not at all.

LoggingInterfaces SHOULD NOT throw exceptions; instead they should log errors using the global logger.

LoggingInterfaces SHOULD provide a named constructor option/field 'logger' that indicates which destination logs are sent to. This option SHOULD default to the rootLogger.

LoggingInterfaces SHOULD provide a named constructor option 'level' and associated field that can be used to limit logging to messages to those with a sufficiently high log level.

LoggingInterfaces SHOULD provide a named constructor option 'filter' and associated field that can be used to transform messages arbitrarily. This option should default to the identity() function from ferrum. If the filter returns undefined the message MUST be discarded.

LoggingInterfaces SHOULD provide a named constructor option 'defaultFields'; if they do support the property they MUST perform a shallow merge/setdefault into the message AFTER applying the filters.

Message

Internally helix log passe these messages around.

Messages are just plain objects with some conventions regarding their fields:

Kind: global interface
Example

const myMessage = {
  // REQUIRED

  level: 'info',
  timestamp: new BigDate(), // Can also be a normal Date

  // OPTIONAL

  // This is what constitutes the actual log message an array
  // of any js objects which are usually later converted to text
  // using `tryInspect()`; we defer this text conversion step so
  // formatters can do more fancy operations (like colorizing certain
  // types; or we could)
  message: ['Print ', 42, ' deep thoughts!']
  exception: {

    // REQUIRED
    $type: 'MyCustomException',
    name; 'MyCustomException',
    message: 'Some custom exception ocurred',
    stack: '...',

    // OPTIONAL
    code: 42,
    causedBy: <nested exception>

    // EXCEPTION MAY CONTAIN ARBITRARY OTHER FIELDS
    ...fields,
  }

  // MESSAGE MAY CONTAIN ARBITRARY OTHER FIELDS
  ...fields,
}

Logger