highlogger

With the recent changes to bunyan there is no more need for highlogger so I recommend switching since highloggerer will not be maintained anymore.

Installation

$ npm install highlogger

Features

• log to multiple transporters at once, depending on message severity
• set severity range per transporter, each transporter will only log messages within its severity range
• available transporters:
  • console
  • socket (only udp4 right now)
  • syslog (implemented after RFC5424, only udp4 right now, structuredData & messageId not supported)
  • S3 bucket
• debug environment variable
  • white- and blacklisting for debug messages based on their debug key
• can be used as singleton
• configurable maximum message length per transporter
• support for a fallback transporter in case maximum message length was exceeded
• supports loading config via config module if present
• adds a context to each message
  • default context is the filename of the log-method caller
  • custom context can also be set

Quick Start

let Highlogger = require('highlogger');
let log = new Highlogger();

log.error('this is a error message');
log.notice('this is a notice message');

Highlogger has to be configured according to your demands.
Per default Highlogger will log to console (process.stdout & process.stderr).
Debug messages will only be shown if the environment is set.

Setup

Highlogger has to be instanced at least once before you can use it.
It will accept an array (also a collection) of transporter configs as a parameter for configuration.

Example with parameter

let Highlogger = require('highlogger');
let config = [
  {type: 'console'}
];

let log = new Highlogger(config);

If you have the config module installed your config will also be attempted to be read from the key highlogger

Example default.yml

highlogger:
  -
    type: console

Example setup

let Highlogger = require('highlogger');
let log = new Highlogger();

Configuration

type: array

The configuration array has to be an array (or collection) of transporter configurations.
Configuration is always on a per-transporter basis.

Example

[
  {type: 'console'},
  {type: 'syslog'}
]

Common Transporter Configuration

Config fields supported by every transporter:

field	type
type	string
sizeLimit	number
severityMin	string
severityMax	string
json	boolean
fallback	object
useContext	boolean

Example (collection)

{
  0: {
    type: 'console',
    json: false,
    sizeLimit: 512
  },
  1: {
    severityMin: 'crit',
    type: 'syslog'
  }
}

type

type: string
required
Available types: console • socket • syslog

Defines the type of a transporter.

sizeLimit

type: number
default: Infinity

This determines the maximum amount of characters a transporter should allow for a message.
If the maximum is exceeded the transporter will log a corresponding error message.
In case of an exceeded maximum a fallback transporter, if available, will log the full message.

severityMin

type: string
default: emerg
Available severities: emerg • alert • crit • error • warn • notice • info • debug

Defines the minimum severity a transporter will log.
emerg is the lowest severity while debug is the highest.

severityMax

type: string
default: debug
Available severities: emerg • alert • crit • error • warn • notice • info • debug

Defines the maximum severity a transporter will log.
emerg is the lowest severity while debug is the highest.

json

type: boolean
default: false

If enabled will wrap every message as a stringified JSON object.

Non-objects will be wrapped under a message-key:
"foobar" would become {"message":"foobar"}.

Objects (or errors & arrays) will be stringified:
{err: 'or', foo: 'bar'} would become {"err":"or","foo":"bar"}

fallback

type: object

This is an optional field that, if set, expects another transporter configuration.
The configured "fallback transporter" will be used when the original transporter can not log a message.
Currently the fallback would only be used when a message exceeds the original transporters sizeLimit.

Example

[
  {
    type: 'syslog',
    sizeLimit: 100,
    fallback: {
      type: 'console'
    }
  }
]

useContext

type: boolean
default: false

If enabled a context will be added to every logged message.
If json is disabled the context will be prepended to any message,
if json is enabled it will be added as a separate key.

Normally the context will be the filename of the log-function caller. A custom context can also be set via one of the get-Methods like getError(context)

Console Transporter Configuration

colors

type: boolean
default: tries to determine if the console supports colors

Decides whether or not messages for this transporter will be colored.

Socket Transporter Configuration

method

type: string
required

Currently only supports udp4

address

type: string
required

The target IP (like 127.0.0.1 or localhost).

port

type: number required

The target port.

sizeLimit

type: number
default: 512

Default of 512 for socket transporters to avoid problems with udp.

Syslog Transporter Configuration

facility

type: string
default: user
Available facilities:
kern • user • mail • daemon • auth • syslog • lpr • news • uucp • clock • sec • ftp • ntp • audit • alert • clock2 • local0 • local1 • local2 • local3 • local4 • local5 • local6 • local7

hostname

type: string
default: tries to determine local hostname

Will be filtered to PRINTUSASCII and a maximum of 255 characters.

appName

type: string
default: value of name set in your package.json

Will be filtered to PRINTUSASCII and a maximum of 48 characters.

processId

type: string
default: process.pid

Will be filtered to PRINTUSASCII and a maximum of 128 characters.

timezoneOffset

type: number
default: attempts to determine your systems offset from UTC time

Allows you to set a custom timezone offset from UTC time in hours.
Value must be between -16 to 16 hours.

method

type: string
default: udp4

Currently only supports udp4

address

type: string
default: 127.0.0.1

The target IP (like 127.0.0.1 or localhost).

port

type: number
default: 514

The target port.

sizeLimit

type: number
default: 512

Default of 512 for syslog transporters to avoid problems with udp.
Keep in mind that the syslog message prefix will also count into this size limit.

S3 Transporter Configuration

accessKeyId

type: string
required

Your AWS access key ID.

secretAccessKey

type: string
required

Your AWS secret access key.

bucket

type: string
required

Name of the bucket to which the message should be saved.

region

type: string
required

The region where the bucket is located. Possible values include:

• us-west-1
• us-west-2
• eu-west-1
• eu-central-1
• ap-northeast-1
• ap-northeast-2
• ap-southeast-1
• ap-southeast-2
• sa-east-1

appName

type: string
default: value of name set in your package.json

Will be prepended to the key with a slash like appName/context-UUID

sessionToken

type: string

Optional AWS session token to sign requests with.

acl

type: string
default: set by the AWS-SDK

The canned ACL to apply to the message. Possible values include:

• private
• public-read
• public-read-write
• authenticated-read
• aws-exec-read
• bucket-owner-read
• bucket-owner-full-control

maxRetries

type: number
default: set by the AWS-SDK

The maximum amount of retries to attempt.

ssl

type: boolean
default: set by the AWS-SDK

Whether to enable SSL.

fallbackPrefix

type: string

Only in case S3 transporter is used as fallback.
This string will be prepended to the location of the logged message in S3 and sent to the original transporter.

Singleton

Highlogger needs to be instanced at least once with your desired configuration.
You can then access the same instance with Highlogger's singleton functionality.

Example

let Highlogger = require('highlogger');
new Highlogger();
let log = Highlogger.getInstance();

log.notice('this is a error message');

Reload

You can call reload(config) on an Highlogger instance to have that instance reload (and replace) it's transporters.

Usage

Highlogger instances offer logging methods for each supported severity,
as well as 'getter' methods that allows you to overwrite the message context.

Example

let logger = new Highlogger();

logger.warn(message0, message1, messageN);

At least one message parameter is required.

Debug

You can set debug contexts per environment variable DEBUG by passing a comma-separated list of contexts.
* as wildcard is supported

Messages with debug severity will be omitted unless a matching context environment was set.
To see all debug messages you can set DEBUG=*

You can also exclude specific contexts by prefixing them with a -.
DEBUG=*,-foo* would include all contexts except those starting with 'foo'.

Available methods

Highlogger instances expose several methods.

Direct logging methods are:
emerg() • alert() • crit() • error() • warn() • notice() • info() • debug()

Each of those methods accepts one parameter of any type.
This parameter will be sent to all transporters with a matching severity range.

The filename of the caller of any of these methods will be added as context is useContext is enabled.
This means if you try to log 'foobar' like log.notice('foobar'); from a file "filename.js":

• json disabled, context will just be prepended: filename.js foobar
• json enabled, context will be added as a key: {"message":"foobar","context":"filename.js"}

debug() logs will be omitted unless their context matches the DEBUG environment.

Example

let Highlogger = require('highlogger');
let log = new Highlogger();

log.emerg("emergency message");
log.alert("alert message");
log.crit("critical message");
log.error("error message");
log.warn("warning message");
log.notice("notice message");
log.info("information message");
log.debug("debug message");

Sometimes it might be useful to set a custom context.
You can use these methods to get log methods with your custom context:
getEmerg() • getAlert() • getCrit() • getError() • getWarn() • getNotice() • getInfo() • getDebug()

This will only work for transporters with useContext enabled.

Example

let Highlogger = require('highlogger');
let log = new Highlogger();
let myAlert = log.getEmerg('customContext');

myAlert("foobar");

Depending on the transporters json setting, this would either log
customContext foobar or {"message":"foobar","context":"customContext"}

Tests

Run unit tests:

$ npm test

Check test coverage:

$ npm run cover

Todo

• add file transporter
• support for external transporter plugins
• unix-domain support for socket transporter
• tcp4/6 support for socket transporter
• udp6 support for socket transporter

People

The original author of Highlogger is Metin Kul

List of all contributors

License

MIT