g-log

npm install --save g-log

const GLog = require('g-log');

GLog.info('The default logger prints to the console');

// => [1491231854012][INFO] The default logger prints to the console

var child = GLog.child({ $tags: 'APP' });
child.info('Create child logs with tags and metadata');

// => [1491231854012][INFO][APP] Create child logs with tags and metadata

var fileTransport = new GLog.Transports.File('path/to/my/log.log');
child.transports.push(fileTransport);

child.info('This log will go to both the console, and the log file!', { meta: 'data' });

// => [1491231854012][INFO][APP] This log will go to both the console, and the log file!
// => {"$tags":["APP"],"meta":"data","time":1491231854012,"level":"info","text":"This log will go to both the console, and the log file!"}

var nextChild = GLog.child({ $tags: 'COMPONENT' });
nextChild.info('Tags are preserved when creating children');

// => [1491231854012][INFO][APP][COMPONENT] Tags are preserved when creating children
// => {"$tags":["APP","COMPONENT"],"meta":"data","time":1491231854012,"level":"info","text":"Tags are preserved when creating children"}

Metadata

Metadata is attached to logs as simple javascript objects. There is currently one reserved key, $tags which is an array of strings used as tags for the log message. When creating child logs, this key is created by concatenating the parent's Logger#meta.$tags with the child's.

API

Modules

GLog : Logger

The main exports. GLog is an instance of Logger, so it will have all associated properties and methods.

Classes

Logger

Transport

Console ⇐ Transport

File ⇐ Transport

Stream ⇐ Transport

GLog : Logger

The main exports. GLog is an instance of Logger, so it will have all associated properties and methods.

• GLog : Logger
  • .version : string
  • .Logger : Logger
  • .Transport : Transport
  • .Transports : object
    • .Console : Console
    • .File : File
    • .Stream : Stream
  • .levels : object
  • .create(level, meta, config) ⇒ Logger
  • .exists(name) ⇒ boolean
  • .get(name, defaultLevel) ⇒ Logger
  • .remove(name)

GLog.version : string

Kind: static property of GLog
Read only: true

GLog.Logger : Logger

A reference to the Logger class

Kind: static property of GLog
Read only: true

GLog.Transport : Transport

A reference to the Transport class

Kind: static property of GLog
Read only: true

GLog.Transports : object

A reference to the list of transports

Kind: static property of GLog
Read only: true

• .Transports : object
  • .Console : Console
  • .File : File
  • .Stream : Stream

Transports.Console : Console

Kind: static property of Transports

Transports.File : File

Kind: static property of Transports

Transports.Stream : Stream

Kind: static property of Transports

GLog.levels : object

A reference to levels

Kind: static property of GLog
Read only: true

GLog.create(level, meta, config) ⇒ Logger

Convenience method for creating new loggers.

Kind: static method of GLog

Param	Type	Description
level	number	The level to log at
meta	object	Metadata to attach to all messages
config	object	Additional configuration for the logger
config.transports	array	Where to send our log messages.

GLog.exists(name) ⇒ boolean

Checks whether the named log exists.

Kind: static method of GLog

Param	Type
name	string

GLog.get(name, defaultLevel) ⇒ Logger

Returns the log with name, instantiating it if necessary.

Kind: static method of GLog

Param	Type
name	string
defaultLevel	string

GLog.remove(name)

Removes the named log from logs.

Kind: static method of GLog

Param	Type
name	string

Logger

Kind: global class

• Logger
  • new Logger(level, meta, config)
  • instance
    • .meta
    • .name
    • .transports
    • .level
    • .remove
    • .mergeMeta() ⇒ object
    • .log(level, msg, logmeta)
    • .child(level, meta, config)
  • static
    • .levels : object
    • .logs : object
    • .setLevels(levels)
    • .nextid() ⇒ number

new Logger(level, meta, config)

Our core logger class. Contains the logging methods, and allows you to create child logs. In addition to the listed methods, there will be a method for each logging level, that simply redirects to log with a set level argument (these are generated by setLevels).

Param	Type	Description
level	number	The level to log at
meta	object	Metadata to attach to all messages
config	object	Additional configuration for the logger
config.name	string	A name that we can use to retrieve our log.
config.transports	array	Where to send our log messages. Defaults to a new Console transport.

logger.meta

The metadata to attach to all messages. Keys can be overwritten in individual logs.

Kind: instance property of Logger
Properties

Name	Type
meta	object

logger.name

The name used to refer to this log in get, exists, and remove

Kind: instance property of Logger
Properties

Name	Type
name	string

logger.transports

The array of transports used by this log.

Kind: instance property of Logger
Properties

Name	Type
transports	Array.<Transport>

logger.level

The current logging level. Will be converted to a number when set with a string.

Kind: instance property of Logger
Properties

Name	Type
level	number

logger.remove

Removes the reference to this log from GLog.logs.

Kind: instance property of Logger

logger.mergeMeta() ⇒ object

Merges any number of metadata objects together.

Kind: instance method of Logger
Returns: object - The merged metadata.

logger.log(level, msg, logmeta)

Logs a message to the current transports if and only if Logger#level is greater than or equal to level.

Kind: instance method of Logger

Param	Type	Description
level	string	The name of the current level.
msg	string	The message to be logged.
logmeta	object	Additional metadata to be logged.

logger.child(level, meta, config)

Creates a new logger using all of the same settings as the parent, unless modified in config. Also merges meta with the parent's metadata.

Kind: instance method of Logger

Param	Type	Description
level	number	The initial level to log at.
meta	object	Permanent metadata to add to the parent's.
config	object	Extra configuration (overwrite parent's).

Logger.levels : object

A set of levels in the form name: level. Lower level means more important (error is usually 0). This property should not be set directly, instead use setLevels.

Kind: static property of Logger

Logger.logs : object

A container that holds all instantiated logs.

Kind: static property of Logger

Logger.setLevels(levels)

Sets the levels and creates the corresponding methods used by all logs (including already instantiated ones).

Kind: static method of Logger

Param	Type	Description
levels	object	A set of levels in the form name: level. Lower level means more important (error is usually 0).

Logger.nextid() ⇒ number

Returns a (usually) unique id

Kind: static method of Logger

Transport

Kind: global class

• Transport
  • new Transport(level)
  • .level
  • .log(string, data)

new Transport(level)

Base class for transports.

Param	Type	Description
level	number	The level to log at.

transport.level

The current logging level. Will be converted to a number when set with a string. This can be set independently of the logger's level (but the logger won't pass on any messages above its own level).

Kind: instance property of Transport
Properties

Name	Type
level	number

transport.log(string, data)

Implemented by subclasses. What we actually do with the log message once it's ready.

Kind: instance abstract method of Transport

Param	Type	Description
string	string	The message in JSON form.
data	string	The message in object form.

Console ⇐ Transport

Kind: global class
Extends: Transport

• Console ⇐ Transport
  • new Console(level, formatter)
  • .level
  • .format(message) ⇒ string
  • .log(string, data)

new Console(level, formatter)

Outputs log messages to the console, via a formatter function.

Param	Type	Description
level	number	The level to log at.
formatter	function	A function that accepts the object form of the message, and returns a string to be logged via console.log.

console.level

The current logging level. Will be converted to a number when set with a string. This can be set independently of the logger's level (but the logger won't pass on any messages above its own level).

Kind: instance property of Console
Properties

Name	Type
level	number

console.format(message) ⇒ string

The default format function.

Kind: instance method of Console

Param	Type	Description
message	object	The object form of a message to be logged.

console.log(string, data)

Logs a message to the console.

Kind: instance method of Console
Overrides: log

Param	Type	Description
string	string	The message in JSON form.
data	string	The message in object form.

File ⇐ Transport

Kind: global class
Extends: Transport

• File ⇐ Transport
  • new File(level, path, options)
  • .level
  • .log(string)

new File(level, path, options)

Outputs log messages to a file as line-delimited JSON.

Param	Type	Description
level	number	The level to log at.
path	string	The path to the log file.
options	object	Additional options to pass to fs.createWriteStream.

file.level

The current logging level. Will be converted to a number when set with a string. This can be set independently of the logger's level (but the logger won't pass on any messages above its own level).

Kind: instance property of File
Properties

Name	Type
level	number

file.log(string)

Writes the JSON form of a log message to the file stream.

Kind: instance method of File
Overrides: log

Param	Type	Description
string	string	The message in JSON form.

Stream ⇐ Transport

Kind: global class
Extends: Transport, node.Stream.Readable

• Stream ⇐ Transport
  • new Stream(level)
  • .level
  • .log(string, data)

new Stream(level)

Outputs log messages as a readable stream.

Param	Type	Description
level	number	The level to log at.

stream.level

The current logging level. Will be converted to a number when set with a string. This can be set independently of the logger's level (but the logger won't pass on any messages above its own level).

Kind: instance property of Stream
Properties

Name	Type
level	number

stream.log(string, data)

Pushes the log message into the stream, delimited with a newline.

Kind: instance method of Stream
Overrides: log

Param	Type	Description
string	string	The message in JSON form.
data	string	The message in object form.