record-keeper
v0.1.0
Published
A javascript package for recording named values at different verbosity levels
Downloads
1
Readme
record-keeper
A smarter logging practice: instead of leaving a trail of breadcrumbs in your logs, use this to record a collection of named values that you care about, the values that will help you understand whatever it is that you want to understand about your execution. You can then dump the collection into your logs at the end of the execution, all in one neat tidy little package, instead of splattered across countless lines of logs interleaved with lines from concurrent executions.
Overview
Install as you would expect, it's an javascript package published to npm:
npm install --save record-keeper
.
Instantiate a RecordKeeper
, and start adding records to it. Each record has a name,
a value, and a verbosity level: how verbose do the logs need to be in order to include
this log (more on this below).
const RecordKeeper = require("record-keeper");
const keeper = new RecordKeeper();
keeper.recordValue("foo", "some value", 10);
keeper.recordValue("bar", "some debug value", 50); // higher value means more verbose
Before your execution terminates, get the records, and dump them to your logs,
however you would normally log. Decide what level of verbosity you want to
include, and pass it to the getRecords
method:
// Will include any records that were added with a verbosity of 10 or less.
console.log(keeper.getValues(10));
Records
A record is just a named value. It can be any javascript value. For logging purposes, you'll probably want to use something that can be serialized to JSON or some other format, but that's really between you and your logger.
Verbosity
The basic premise here is that when your execution follows the happy path, you probably don't need to know too much about the execution, you can use a relatively low verbosity. However, when something goes wrong, you might want more data, so you want a higher verbosity.
When you add a record, you specify it's verbosity level. When you're ready to log the records, you decide what level of verbosity you need, and ask for records that have that verbosity or lower.
For instance, if you define "DEBUG" to be a higher verbosity than "INFO", and "INFO" to be a higher verbosity than "ERROR", then ask for records with verbosity "INFO", you'll get back any values that were added with "INFO" or "ERROR", but not any that were added with "DEBUG": these are more verbose than what you asked for.
Verbosity isn't actually associated with a record, but with a value for a record. For instance, you can add a record named "foo" with a high verbosity, giving it a value of "really long string with lots of details", then add it again with a lower verbosity, giving it a value of "summary". Then when you ask for records with the higher verbosity, you'll get the more detailed value; when you ask for records with the lower verbosity, you'll get the summary value.
If you find "verbosity" to be unintuitive, you might try thinking of it as priority instead, where a low value is a higher priority (e.g., a value of 1 is the number-one priority). High-priority records are more like to be included in the logs.
Lazy Values
Use the recordLazy
method to add a lazy value: these are just like a regular record except
instead of giving the value of the record, you give a supplier function which can be used to get
the value. The supplier function will be invoked at most once, the first time that the value is
actually delivered through the getRecords
function. The result of the supplier function will be
used as the value of the record, and will be cached for subsequent use of that record.
Record Multiple
You can write multiple records to the same level using the recordValues
method. Instead of taking
a record name and a value as two arguments, it takes an object whose own properties are used as
a dictionary of records to add.
Named levels
You can create a subtype of RecordTracker
using the RecordTracker.define
function. It takes an
object/dictionary of named verbosity/priority levels and adds these as convenience methods to the
prototype. For instance:
const MyTracker = RecordTracker.define({
critical: 1,
useful: 10,
debug: 20
});
const tracker = new MyTracker();
tracker.at.critical.recordValue("input", "the input values");
tracker.at.useful.recordValue("output", "the result");
tracker.at.debug.recordValue("something", "that isn't very useful");
console.log(tracker.getRecords.useful()); // { input: ..., output: ... }