snog

A simple strutured logging library for node. Heavily inspired by Logrus.

npm i @openfin/snog

Latest Stable: 2.0.0

Usage

You can use snog directly aka the default global logger.

import log from "@openfin/snog";
log.debug("hello");

Or clone / create a new one

import log, { Snog } from "@openfin/snog";
const clonedLogger = log.clone();
const newLogger = new Snog();

See snog.clone for the difference between clone and new.

You can log with fields

import log from "@openfin/snog";
log
  .addField("I love", "pizza")
  .addField("I love", "grits")
  .addFields({ like: "oranges" })
  .info("food i love");
// Note: Fields with the same name will override previous fields

log.silly(...values)

log.debug(...values)

log.info(...values)

log.warn(...values)

log.error(...values)

Logs the given values at the respective level

log.sillyF(format, ...values)

log.debugF(format, ...values)

log.infoF(format, ...values)

log.warnF(format, ...values)

log.errorF(format, ...values)

Logs the given values after formatting with util.format. See documentation on util.format for more information.

log.addField(fieldName:string, value:any)

Adds a field to be logged when a logging method is called. Fields can over write each other, the latest one taking precendence. Also nothing is logged until a log method(eg log.info) is called

log.addFields(fields:Object)

Similar to .addField but takes an object instead of a key/value pair

log.setLevel(logLevel:int|string)

Set the log level using either the logLevel enum integer or a log level string(silly, debug, info, warn, error). If you pass something invalid it will not change the level. It will print a error message. Returns false if the level was not changed otherwise true.

log.clone(snogOptions)

Takes the same options as creating a new Snog instance directly, only difference is that clone will merge defaultFields and keep custom formater, writer and previous level. Just a small convience function for those who want "child logger" like functionality.

Configuration

Both .clone and new Snog take the same options object.

• colorize OPTIONAL: Colorize the terminal output. If the environment variable NODE_ENV is set to production colorize is set to false, otherwise it defaults to true.
• defaultFields OPTIONAL: Fields to always log.
• level OPTIONAL: Log level. If the environment variable NODE_DEBUG is set to a valid level(see Log Levels), it will use that otherwise defaults to INFO
• date OPTIONAL: A function that returns a date object. This is used for testing and should never be set.
• writer OPTIONAL: The log writer, defaults to console.log.
• formatter OPTIONAL: The log formatter. Defaults to built in text formatter. See formatter section for more details

Format and Formatters

You can customize the output of Snog by using a custom formatter. Snog comes with two formatters, textFormatter and jsonFormatter. Snog defaults to textFormatter.

Text formatter output

2018-04-28T04:00:00.000Z INFO msg=Single added field I have='a field'

JSON formatter output

{"I have":"a field","msg":"Overriden","timestamp":"2018-04-28T04:00:00.000Z","level":"INFO","Field 1":1,"Field 2":"another field","im":"an object fields\\n","snog":"true","thisGetsOverriden":"YES"}

You can create your own formatter and pass it to snog provided it matches the formatter interface. For example here is the jsonFormatter

//Snog fields contain the log message(msg), timestamp and level
// fields is the fields the caller added to the log using .addField and/or .addFields
export interface Formatter {
  (snog: Snog, snogFields: SnogFields, fields: Map<string, any>): any;
}

export function jsonFormatter(
  snog: Snog,
  snogFields: SnogFields,
  fields: Map<string, any>
) {
  const k = Object.assign(snog.defaultFields, mapToObject(fields), snogFields, {
    timestamp: snogFields.timestamp.toISOString(),
    level: levelText[snogFields.level]
  });
  return JSON.stringify(k, null, 0) + "\n";
}

Writers

You can change where snog writes to by passing in a custom writer. The writer must be a function that takes a single value and can return anything(prefer void). By default snog uses console.log

Example custom writer

function myAwesomeWriter(input) {
  myCustomStream.write(input);
}
const logger = new Snog({ writer: myAwesomeWriter });

License

Apache 2.0 See LICENSE for more details