@lumbermill/browser
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 browser specific package of the lumbermill logging library. For use in other environments (currently just nodejs), see the parent project README.md.
Usage
This module provides bundles in a number of different formats for different use cases:
Use via webpack/rollup/another bundler
Simply import like any other es module.
import lumbermill from '@lumbermill/browser';
const log = lumbermill('my-bundled-app')Include in html via CDN and <script/> tag
<script src="<baseurl>/browser.iife.js"></script>
<script>
localStorage.debug = "*";
const log = lumbermill('sample-iife', {
app: 'sample-app',
});
log.info('hello world!');
</script>Create a logger instance
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-functionwild-function
Lumbermill allows your to selectively enable logs using wildcards. To enable logs, you set the debug variable in the browser's localStorage. 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
localStorage.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
localStorage.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
localStorage.debug = '*feature*,wild-function';You can also programatically enable a logger:
import lumbermill from '@lumbermill/browser';
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,
prefixContext: {}, // any data here will always be included in every log message with that same prefix
}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:
import lumbermill from '@lumbermill/browser';
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:
import lumbermill from '@lumbermill/browser';
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:
import lumbermill from '@lumbermill/browser';
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:
