lesslog
Zero-dependency, teeny-tiny and serverless-ready logging utility for Node.js.
In most serverless environments log ingestion comes at a cost. And more often than not, those logs are not even looked at for most of the times. Until something goes bad and crucial debugging information is not available, as it was filtered to save on log ingestions.
Using lesslog
, debug information is not logged immediately, but buffered internally. Once an error is logged any buffered logs will be emitted, preserving their original timestamp and context. No debug information is lost, while still maintaining clutter-free logs the rest of the time.
AWS Lambda & CloudWatch
lesslog
was created with AWS Lambda in mind and its default logging format is optimized for Amazon CloudWatch. As Lambda functions are reused as much as possible, clear
must be called at the end of each Lambda execution to prevent the internal buffers to bloat and carry over log messages from previous executions. To resemble Lambda's default log message format, tag
must be used at the very beginning of each execution, to add the awsRequestId
to the logs.
Installation
$ npm install lesslog
Usage
import { clear, debug, info, warn, error, tag } from 'lesslog'
tag('70e505ba-ad84-4816-82ec-f2a1ed4303ca')
debug('Debug message', { with: 'additional', information: true })
info('Uncritical exceptional information', ['maybe', 'an', 'array', '?'])
warn('Potentially critical warning', { tokenExpired: true, user: { id: 42 } })
error('‾\\_(ツ)_/‾', { error: { message: error.message }, user: { id: 42 } })
debug('Yet another debug message')
clear()
Running the above code, will result in the following log messages:
2038-01-19T03:14:07.998Z 70e505ba-ad84-4816-82ec-f2a1ed4303ca INFO Uncritical exceptional information ["maybe","an","array","?"]
2038-01-19T03:14:07.999Z 70e505ba-ad84-4816-82ec-f2a1ed4303ca WARN Potentially critical warning {"tokenExpired":true,"user":{"id":42}}
2038-01-19T03:14:07.997Z 70e505ba-ad84-4816-82ec-f2a1ed4303ca DEBUG Debug message {"with":"additional","information":true}
2038-01-19T03:14:08.000Z 70e505ba-ad84-4816-82ec-f2a1ed4303ca ERROR ‾\_(ツ)_/‾ {"error":{"message":"Original error message"},"user":{"id":42}}
Note the last debug log is not emitted as error
is not called afterwards.
API
clear() => Buffer
Clears and returns the entire internal buffer.
Must be called whenever error
is not invoked and the previous debug messages can be discarded to prevent the internal buffers to bloat.
debug(message: string, context?: any) => void
Stores a log message in the internal buffers.
If the DEBUG
environment variable is set to either '1'
, 'on'
, 'true'
, or 'yes'
, the log message will not be stored and instead written to process.env.stdout
directly.
info(message: string, context?: any) => void
Writes a log message to process.env.stdout
.
warn(message: string, context?: any) => void
Writes a log message to process.env.stderr
.
error(message: string, context?: any) => void
Writes a log message to process.env.stderr
after triggering any internally buffered logs to be written to process.env.stdout
.
tag(tag: string) => void
Adds a given tag to all subsequent log messages.
untag() => void
Removes a previously set tag and stops adding it to subsequent log messages.
set(name: string, value: string | number | boolean | null) => void
Sets a given name-value pair on the default context to be logged with every log message.
The default context and individual log context will be merged together with defaults being overwritten by values in the individual context
argument.
unset(name: string) => void
Removes a name-value pair from the default context by given name.
reset() => void
Clears the entire default context and removes any previously set tag.
Advanced Usage
import log from 'lesslog'
const label = 'MONITORING'
function format(timestamp, label, message, context) {
const metrics = [message, ...context].join('|')
return `${new Date(timestamp).toISOString()}\t${label}\t${metrics}`
}
const logMetrics = log(label, format)
log.tag('14968fcb-6481-46d8-a068-b97d4be47852')
logMetrics('DBQueryMetrics', [42, 0.618, 'readreplica'])
Running the above code, will result in the following log messages:
2038-01-19T03:14:08.000Z 14968fcb-6481-46d8-a068-b97d4be47852 MONITORING DBQueryMetrics|42|0.618|readreplica
log(label: string, format?: Function) => (message: string, context?: any)
Creates and returns a custom log function to write log message directly to process.env.stdout
.
A custom formatting function can be passed as a second argument, which will always be invoked with the following arguments:
Argument | Type | Description |
---|---|---|
timestamp |
number | Milliseconds since 1970-01-01T00:00:00.000Z |
label |
string | The lable used to create the custom log function |
message |
string | Log message passed to the custom log function |
label |
any | Optional context passed to the custom log function |