lumberkit

A simple structured logging library for Node


Keywords
logging, structured logging, middleware, instrumentation
License
MIT
Install
npm install lumberkit@1.0.2

Documentation

LumberKit

A simple structured logging library for Node.

Getting Started

Add the lumberkit package as a dependency to your package.json:

npm install --save lumberkit

If you wish to use the latest (unstable) from master:

npm install --save https://github.com/tombell/lumberkit.git

You are now ready to go ahead and use LumberKit in your project.

Configuration

You can configure LumberKit via the init function.

 Timestamps

You can enable timestamps that will include a now key and ISO date as the value.

const LumberKit = require("lumberkit");

LumberKit.init({ timestamps: true });

LumberKit.log({ at: "deploy" });

This will output something like the following.

now="2016-07-15T13:57:46.749Z" at=deploy

Global Context

You can include a global context of key/values that will be included in every log message.

const LumberKit = require("lumberkit");

const globalContext = {
  pid: process.pid
};

LumberKit.init({ timestamps: true });

LumberKit.log({ at: "deploy" });

This will output something like the following.

now="2016-07-15T13:57:46.749Z" pid=2731 at=deploy

Logging

You can log two types of data, normal key/value data, and errors with additional key/value data.

Notes

  • Floating point numbers will be formatted to 3 decimal places
  • Dates will be formatted as ISO strings
  • Strings will be escaped for backslashes and quotes

Log

You can simply pass an object (objects are not valid values currently).

LumberKit.log({ at: "deploy", user, env: "production" });

This will output something like the following (with timestamps enabled).

now="2016-07-15T13:57:46.749Z" at=deploy user=deploy env=production

 Log Error

You can simple pass an object and a JavaScript error to the logError function.

try {
  foo();
} catch (err) {
  LumberKit.logError({ at: "deploy" }, err);
}

This will output something like the following (with timestamps enabled).

now="2016-07-15T13:57:46.749Z" at=deploy error=ReferenceError message="foo is not defined" site="/Users/tombell/Code/lumberkit/test.js:8:3"

Contributing

When contributing:

  • Avoid complicated code, keep everything simple
  • Use ES6 as supported by the latest Node release
  • Avoid opinionated functionality as best as possible

Pull Requests:

  • Keep the PR title as succinct as possible, include more context in the PR description
  • Always submit a branch for the pull request
  • Remember to update/add any tests when adding/updating functionality