Upgrade GuideLearn how to upgrade to the latest version of LambdaLog.

Version 2.x to 3.x

While there were not a lot of breaking changes to the public API in version 3.0.0, there were several breaking changes internally in LambdaLog. For the most users, upgrading to version 3.0.0 should be seamless.

Breaking Changes

Default log tags have been removed. In the last version of LambdaLog, every log message contained a log and [LEVEL] tag by default and they could not be changed or removed.

For version 3.0.0, these default log message tags have been removed, leaving the _tags array empty by default when a message is logged.

If you want the old functionality back, you can do so by using the following configuration:

1const log = require('lambda-log');
2log.options.tags = ['log', '<<level>>']; 
3 
4log.info('Test');
5// => { "_logLevel": "info", "msg": "Test", "_tags": ["log", "info"] }

Error objects passed into metadata is now converted to a plain object.

Prior to version 3.0.0, any Error objects passed into the metadata for a log was not converted to a plain object leading it to show up as an empty object, because JavaScript. Now Error objects are converted so they can be properly JSON stringified in the output.

A handful of properties on the LogMessage class have been changed to getters/setters.

Before, you were able to directly manipulate these properties on the LogMessage class as needed but this has changed in version 3.0.0. For most of the getters, a corresponding setter has been added to support these changes, but they will also work differently.

 1// Before:
 2const { LambdaLog } = require('lambda-log');
 3const log = new LambdaLog({}, {
 4  unicorn(message) {
 5    // prepend an emoji to every message
 6    message.msg = `🦄 ${message.msg}`;
 7 
 8    // Add additional metadata
 9    message.meta.myProp = 'someValue';
10 
11    // Add tags
12    message.tags.push('new-tag');
13    // or overwrite tags
14    message.tags = ['only', 'these', 'tags'];
15 
16    return 'log';
17  }
18});
19 
20// Now in version 3.0.0:
21const { LambdaLog } = require('lambda-log');
22const log = new LambdaLog({}, {
23  unicorn(message) {
24    // prepend an emoji to every message - This still works the same
25    message.msg = `🦄 ${message.msg}`;
26 
27    // Add additional metadata
28    // The setter function will merge this object into the existing metadata
29    message.meta = { myProp: 'someValue' };
30 
31    // Add tags
32    // The setter concatenates an array of values into the existing tags array
33    message.tags = ['new-tag'];
34 
35    // You can no longer overwrite existing tags
36 
37    return 'log';
38  }
39});

Interal properties on both the LambdaLog and LogMessage classes are now referenced using Symbols instead of standard property names.

If you were implementing advanced custom code for LambdaLog, this may impact you. All of the existing private properties on the two classes were originally named, starting with an underscore. In version 3.0.0, this has changed to use a Symbol as the name. In the cases where you need to access these properties, a new static property, symbols has been added to both classes that allow access to the Symbols being used within the class.

 1// Before:
 2const log = require('lambda-log');
 3 
 4// Manually override log level configuration
 5log._logLevels.error = 'log';
 6 
 7// Now in version 3.0.0:
 8const log, { LambdaLog } = require('lambda-log');
 9 
10// Manually override log level configuration
11log[LambdaLog.symbols.LEVELS].error = 'log';
12 
13// Although a new method was created to make this easier:
14const log = require('lambda-log');
15 
16log.addLevel('error', 'log');

See the API Reference and Changelog for more information.