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