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

Classes

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
  • .exists : function
  • .get : function
  • .remove : function
  • .levels : object
  • .create ⇒ Logger

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.exists : function

A reference to exists

Kind: static property of GLog
Read only: true

GLog.get : function

A reference to get

Kind: static property of GLog
Read only: true

GLog.remove : function

A reference to remove

Kind: static property of GLog
Read only: true

GLog.levels : object

A reference to levels

Kind: static property of GLog
Read only: true

GLog.create ⇒ Logger

Convenience method for creating new loggers.

Kind: static property 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. |

Logger

Kind: global class

• Logger
  • new Logger(level, meta, config)
  • instance
    • .level
    • .remove
    • .mergeMeta() ⇒ object
    • .log(level, msg, logmeta)
    • .child(level, meta, config)
  • static
    • .levels : object
    • .logs : object
    • .exists(name) ⇒ boolean
    • .get(name, defaultLevel) ⇒ Logger
    • .remove()
    • .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. |

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 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.exists(name) ⇒ boolean

Checks whether the named log exists.

Kind: static method of Logger

| Param | Type | | --- | --- | | name | string |

Logger.get(name, defaultLevel) ⇒ Logger

Returns the log with name, instantiating it if necessary.

Kind: static method of Logger

| Param | Type | | --- | --- | | name | string | | defaultLevel | string |

Logger.remove()

Removes the named log from logs.

Kind: static method 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. |