API ReferenceComplete reference of the LambdaLog API.

functionconstructor([options], [levels])

this

Constructor for the LambdaLog class. Provided to be utilized in more advanced cases to allow overriding and configuration. By default, this module will export an instance of this class but you may access the class and create your own instance via log.LambdaLog.

Parameters

propertylog.options

Object

Configuration object for LambdaLog. All options are optional. Most options can be changed at any time via log.options.OPTION = VALUE; unless otherwise noted. Options changed using log.options apply to the specific instance of LambdaLog. If you need to use different options throughout your app, it's best to create a new instance of LambdaLog for each corresponding need.

Properties

functionlog.<info|warn|error|debug|*>(msg, [meta], [tags])

LogMessageBoolean

Shortcut methods for log.log(). By default, the following methods are available: log.info(), log.warn(), log.error() and log.debug(). Additional methods will be added for any custom log levels provided. This method will return the instance of LogMessage or false if debug logs are enabled and you are calling log.debug().

The provided msg can be any type, although a string or Error is recommended. If Error is provided the stack trace is added as metadata to the log as stack.

Custom Log Levels have been deprecated in version 3.1.0 and will be removed in version 4.0.0. Once removed, this shortcut methods will only be added for the built-in log levels.

Parameters

Example

1const log = require('lambda-log');
2 
3log.info('Test info log'); 
4log.debug('Test debug log'); 
5log.warn('Test warn log'); 
6log.error('Test error log'); 
7 
8log.error(new Error('There was an error!')); 
9log.info('Success!', { stats }, ['success']); 

functionlog.log(level, msg, [meta], [tags])

LogMessageBoolean

Generates JSON log message based on the provided parameters and the global configuration. Once the JSON message is created, it is properly logged to the console and emitted through an event. If an Error or Error-like object is provided for msg, it will parse out the message and include the stacktrace in the metadata. This method will return the instance of LogMessage or false if debug logs are enabled and you using the debug log level.

Parameters

Example

1log.log('error', 'Something failed!');
2// same as:
3log.error('Something failed!');

function

1.4.0

log.assert(test, msg, [meta], [tags])

LogMessageBoolean

Generates a log message if test is a falsy value. If test is truthy, the log message is skipped and returns false. Allows creating log messages without the need to wrap them in an if statement. The log level will be error.

Parameters

Example

1let results = null;
2// This log will be displayed since `results` is a falsy value.
3log.assert(results, 'No results provided!');
4//=> { msg: "No results provided!" ... }
5 
6// But if they are truthy, the log is ignored:
7results = [1, 2, 3];
8log.assert(results, 'No results provided!');
9//=> false

function

2.3.0

log.result(promise, [meta], [tags])

Promise<LogMessage>

Generates a log message with the result or error provided by a promise. This method does not take a message, instead it uses the result or error of the provided Promise as the message. Useful for debugging and testing.

Parameters

Example

1let promise = new Promise(resolve => resolve('this is a test'));
2 
3log.result(promise);
4// => { "_logLevel": "info", "msg": "this is a test" ... }
5 
6// If the Promise rejects:
7let promise = new Promise((resolve, reject) => reject(new Error('Something failed')));
8log.result(promise);
9// => { "_logLevel": "error", "msg": "Something failed" ... }

function

3.1.0

log.addLevel(name, handler)

this

Add a custom log level to this instance of LambdaLog. A dynamic method for the new log level will be added to the class. If you pass a function as handler, the function is called for each log message with the parameter msg — The LogMessage instance for the current log message — and the function is scoped to the current instance of LambdaLog. This function must return either false to disable the log from being generated or a string console method name such as log, info, warn, error, and debug.

See Custom Log Levels.

Parameters

Example

 1// Add a new level called "fatal" and log messages with "console.error()":
 2log.addLevel('fatal', 'error'); 
 3log.fatal('There was a very bad error');
 4 
 5// With a function: 
 6log.addLevel('trace', function (msg) { 
 7  // Called with param "msg" which is the LogMessage instance for the particular log message. 
 8  // This function is scoped to the LambdaLog instance. 
 9 
10  // If you add your own config option to `log.options`, you can check it here: 
11  if(!this.options.trace) return false; 
12  return 'log'; 
13});
14 
15log.options.trace = true;
16log.trace('This is a trace message');

eventEvent: log

The log event is emitted (using EventEmitter) for every log generated. This allows for custom integrations, such as logging to a thrid-party service. This event is emitted with the LogMessage instance for the log. You may control events using all the methods of EventEmitter.

Example

1log.on('log', message => {
2  // an example would be sending the log message to another service
3  someLogService(message.toJSON());
4});

staticproperty

3.0.0

LambdaLog.symbols

Object

Static object which contains Symbol definitions used within the LambdaLog class. Available only for advanced usage.

The use of Symbols will be removed in the next major release of LambdaLog due to switching to TypeScript.

Properties

functionconstructor(log, opts)

this

Constructor for the LogMessage class. Called with an object log that contains the data for the log message and an object opts which is the LambdaLog options.

Parameters

gettermessage.level

String

Gets the level for this log message.

Example

1const message = log.info('This is an info log');
2console.log(message.level);
3// => "info"

gettermessage.msg

String

Gets the transformed message for this log message.

Alias: message.message

Example

1const message = log.error(new Error('There was an error'));
2console.log(message.msg);
3// => "There was an error"

settermessage.msg = String

Set the message for the log message, overwriting the existing message.

Alias: message.message = String

Example

1const message = log.info('Info message');
2console.log(message.msg);
3// => "Info message"
4 
5message.msg = 'New message';
6console.log(message.msg);
7// => "New message"

gettermessage.meta

Object

Gets the combined metadata for this log message. This includes metadata passed into the log message, global metadata, and dynamic metadata. From version 3.0.0, any Error or Error-like objects found in the root of the metadata will be converted to a plain object.

Example

1log.options.meta = { prop: 'value' };
2const message = log.info('This is an info log', { with: 'metadata', err: new Error('An error') });
3 
4console.log(message.meta);
5// => { prop: 'value', with: 'metadata', err: { message: 'An error', stack: '...' } }

settermessage.meta = Object

Adds or overwrites metadata for the log message while keeping the existing metadata.

Example

1log.options.meta = { prop: 'value' };
2const message = log.info('This is an info log', { with: 'metadata' });
3 
4console.log(message.meta);
5// => { prop: 'value', with: 'metadata' }
6 
7message.meta = { abc: 123, prop: 'newValue' };
8console.log(message.meta);
9// => { prop: 'newValue', with: 'metadata', abc: 123 }

gettermessage.tags

String[]

Gets the tags for this log message. This includes tags passed into the log message and global tags. The tags are generated from strings or by using enhanced tags.

Example

1log.options.tags = ['a-tag', '<<level>>'];
2const message = log.info('This is an info log', {}, ['success']);
3 
4console.log(message.tags);
5// => ['a-tag', 'info', 'success']

settermessage.tags = String[]|Function[]

Adds additional tags to the log message while keeping existing tags. You may include enhanced tags.

Example

1log.options.tags = ['a-tag'];
2const message = log.info('This is an info log', {}, ['success']);
3 
4console.log(message.tags);
5// => ['a-tag', 'success']
6 
7message.tags = ['<<level>>', 'more-tags'];
8console.log(message.tags);
9// => ['a-tag', 'success', 'info', 'more-tags']

gettermessage.value

Object

Gets the compiled log object for this log message. From version 3.0.0, the key names of the properties in this object can be overridden using the options levelKey, messageKey, and tagsKey in log.options. If levelKey or tagsKey is set to null or undefined, those properties will not be included in the output of the log message.

Alias: message.log

Example

1const message = log.info('This is an info log');
2console.log(message.value);
3// => { _logLevel: 'info', msg: 'This is an info log', _tags: [] }

gettermessage.throw

Throws the an error. If an error was not provided, one will be generated for you and thrown. This is useful in cases where you need to log an error, but also throw it.

Example

1log.error('This is an error').throw;
2 
3// Shorthand for:
4let logMsg = log.error('This is an error');
5let error = new Error(logMsg.msg);
6error.log = logMsg;
7 
8throw error;

functionmessage.toJSON([format])

String

Returns the compiled log object converted into a JSON string. This method utilizes log.options.replacer for the replacer function. Uses fast-safe-stringify to prevent circular reference issues. Returns message.value JSON stringified.

Parameters

Example

1log.error('This is an error').toJSON(true);
2// => {
3//      "_logLevel": "error",
4//      "msg": "This is an error",
5//      ...
6//   }

staticfunctionLogMessage.isError(val)

Boolean

Static function that checks if provided val is an Error or Error-like object. Returns true if the provided value is an Error, otherwise false.

Parameters

staticfunctionLogMessage.stubError(err)

Error

Static function that stubs an Error with a toJSON method for easily converting an Error into a plain object.

Parameters

staticproperty

3.0.0

LogMessage.symbols

Object

Static object which contains Symbol definitions used within the LogMessage class. Available only for advanced usage.

Properties