HBK Logger

Here it lies, the great HBK Logger for Node.

This is a basic logger, extracted out of chartroom-api, that makes it very easy to format logs in a Cloudwatch/ElasticSearch/Kibana-friendly way, as an extension of our logging pipeline.

Usage

The quick copypasta to include the logger is to npm install --save @hbkapps/logger and initialize by requiring the file with

var log = require('@hbkapps/logger')(__filename)

wherever you need a logger.

You can also specify an options object, like so:

var log = require('@hbkapps/logger')({
    nameSpace: __filename,
    printWithColors: false
})

The function takes two arguments. The first, if it is a string, is a module path. The second is an options hash. The options can also be provided as the first and only argument.

Accompanying this module is a requestContext module, which can set the global.CONTEXT variable. Anything contained within the global.CONTEXT module will be logged along with the meta data by the logger.

Features

This module is a trimmed down logger, doing pretty much only the essentials. It can be called by by logger.method(msg, meta), or log.log('method', msg, meta)

Module Path Support

By including the __filename when we include the logger, we get to see exactly what module produced that log. That makes it much easier to trace logs across different module. We automatically drop the current working directory of the running process from this string to make it easier to digest (thus all paths are relative to the server's CWD).

Context Support (e.g. API Gateway/Lambda Support via CLS)

The requestContext module allows to set certain context variables such as AWS request id and user agent. It is a standalone module from logger. And whatever is set in the global.CONTEXT will be included in the log output as context. e.g. userId can be set in globalContext.

Automatic STAGE/NODE_ENV logging

If the STAGE or NODE_ENV environmental variables are set, this module will include them in its output. By default, our Serverless configuration automatically sets the STAGE variable, so this should work OOTB.

N.B: For at least chartroom-api, there is no need to fiddle with the NODE_ENV as it should not be used.

Optional File Logging (not yet implemented)

If there is an logOutputPath in the options, the logs will write to disk at the logOutputPath. Note that this module will not create any necessary directories for you.

Object Logging

Need to log an object? Just pass the option as the second parameter to the logger instance, like so:

log.debug('blah', object)

Log Output Structure

With all options filled, the logger will output JSON that looks something like:

 {
    "timestamp": "1507582665044",
    "message": "blah",
    "meta": {
        "ayy": "lmao",
        "lmao": "ayy",
    },
    "userId": "bneese",
    "modulePath": "@crapi-orm/index.js",
    "stage": "STAGING",
    "apiRequestId": "1010101",
    "lambdaRequestId": "1010101"
  };

This object's structure is also documented on line 46-56 of index.js.

Note again that all falsy values will automatically be trimmed from the output.

Full Environmental Variable Documentation

For now, refer to config.json.