@lumbermill/node

Lumbermill is a logging library that has Markdown support, and allows for DEBUG="*" style logging, in both the browser or in nodejs. There are separate packages to keep bundle size small. This project borrows heavily from logdown.

This is the nodejs specific package of the lumbermill logging library. For use in other environments (currently just the browser), see the parent project README.md.

Usage

commonjs

Use it like a standard nodejs library:

const lumbermill = require('@lumbermill/node');

const log = lumbermill('my-nodejs-service');

log.info('hello world');

As an esmodule

Simply import like any other es module.

import lumbermill from '@lumbermill/node';

const log = lumbermill('my-nodejs-service');

log.info('hello world');

API

Create a new logger: lumbermill(prefix, opts)

prefix:

The prefix is basically the name of your logger. It has some fancy abilities however.

You can use globs to determine which loggers will have their output displayed:

Example prefixes:

• my-app:some-feature:some-crazy-function
• my-app:some-feature:another-crazy-function;
• crazy-function
• wild-function

Lumbermill allows your to selectively enable logs using wildcards. To enable logs, you set the env var NODE_DEBUG or DEBUG to a glob.

For example:

// this will enable any loggers that have a prefix that starts with 'my-app',
// so from the above prefixes
// * `my-app:some-feature:some-crazy-function`
// * `my-app:some-feature:another-crazy-function`;
// would have their logs shown
process.env.debug = 'my-app:*';

// this will enable any logger that ends with 'crazy-function',
// so from the above prefixes
// * `my-app:some-feature:some-crazy-function`
// * `my-app:some-feature:another-crazy-function`;
// * `crazy-function`
// would have their logs shown
process.env.debug = '*crazy-function';

// this will enable any logger that has `feature` in the name,
// as well as any logger with the exact prefix 'wilf-function'
// so from the above prefixes
// * `my-app:some-feature:some-crazy-function`
// * `my-app:some-feature:another-crazy-function`;
// * `wild-function`
// would have their logs shown
process.env.debug = '*feature*,wild-function';

You can also programatically enable a logger:

const lumbermill = require('@lumbermill/node');

const log = lumbermill('my-bundled-app');

log.state.isEnabled = true;

options:

Objects is an optional argument to the lumbermill function. It is a javascript object, with the following optional properties:

// the following shows the default values of opts
const opts = {
	// if markdown is true, then markdown within the log message will be parsed
	// and rendered in the log output.
	markdown: true, // default is true
	prefixColor: '#FFEE22', // default is auto chosen from the lumbermill.prefixColors array

	// defaults to console, you can specify a custom output logger
	// basically it takes any function on this object and wraps it
	logger: console,
}

Context

Context is data that is included with each output of your log. It is It can be set at 3 levels:

Global Context:

lumbermill.setGlobalContext(<context object>);

Global context will be the same for every logger you create. It is shared across all lumbermill logger instances.

Example:

const lumbermill = require('@lumbermill/node');

const logA = lumbermill('logA');
const logB = lumbermill('logB');

lumbermill.setGlobalContext({
	app: 'my-app-name',
	userId: 12312512,
});

logA.info('some log message');
logB.info('another log message');

Both of the above logs will have app and userId in their context:

Example Output:

Prefix Context

Prefix context will be the same for all logger instances that share the same prefix. Let's update the global context example to show prefix context.

Example:

const lumbermill = require('@lumbermill/node');

const logA = lumbermill('logA', {
	prefixContext: {
		whatLogAmI: 'I am log A',
		somthing: 'x',
	}
});
const logB = lumbermill('logB', {
	prefixContext: {
		whatLogAmI: 'I am log B',
		somethingElse: 'y',
	}
});

lumbermill.setGlobalContext({
	app: 'my-app-name',
	userId: 12312512,
});

logA.info('some log message');
logB.info('another log message');

Both logger instances will still share the same global context, but the prefixContext will be specific only to them. This will work even within different files in the same app, since lumbermill maintains an internal list of prefix logger instances.

Example Output:

Message Context

loggerInstance.withContext({ someContextData: 'a' }).log('a message with context');

Message context is context data that is only relevant to a single log message. It can be set as follows:

const lumbermill = require('@lumbermill/node');

const logA = lumbermill('logA');

logA.log('a message');

logA.withContext({ someContextData: 'a' }).log('a message with context');

The context will not be persisted and will only be included with that log message. Any global and prefix context will still be combined with it if it exists.

Example Output: