README
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