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