Package detail

lambda-log

KyleRoss203.5kMIT3.1.0

Lightweight logging library for any Node 10+ applications

json, lambda, aws, log

readme

lambda-log

npm npm GitHub Workflow Status Code Climate coverage license Code Climate maintainability CodeFactor Grade Snyk Vulnerabilities for npm package All Contributors

LambdaLog is a Node.js package facilitates and enforces logging standards in Node.js processes or applications anywhere by formatting your log messages as JSON for simple parsing and filtering within log management tools, such as CloudWatch Logs. Works with all of the supported versions of Node.js on Lambda.

Originally created for AWS Lambda Functions, LambdaLog is a lightweight and feature-rich library that has no dependency on AWS or Lambda, meaning you can use it in any type of Node.js project you wish. It's really a universal JSON logger.

Why another lambda logger? There are plenty of other logging libraries in the NPM ecosystem but most are convoluted, included more functionality than needed, not maintained, or are not configurable enough. I created LambdaLog to include the important functionality from other loggers, but still maintaining simplicity with minimal dependencies.

Features

Anyone can log JSON to the console, but with Lambda Log you also get:

  • Metadata and tags that may be set globally or individually for each log message.
  • Error and Error-like objects logged include stacktraces in the metadata automatically.
  • Each log message emits an event to allow third-party integration.
  • Pluggable and customizable by extending the LambdaLog class.
  • Pretty-printing of the JSON log message in dev mode.
  • Well documented, commented, and maintained source code.
  • Over 1.5 million downloads and more than 35k weekly downloads.
  • Small footprint.

New in Version 3.0.0

Version 3.0.0 of Lambda Log brings a bunch of changes, new features, and a new website.

Broad Changes:

  • Refactor all code to meet new ESLint specifications and to stay up-to-date with newer ecmascript specifications.
  • New website with better documentation.
  • Tests are now using Jest instead of Mocha.
  • Switched from TravisCI to Github Actions.

New Features:

  • Added levelKey configuration option to be able to change the key name for log levels.
  • Added messageKey configuration option to be able to change the key name for log messages.
  • Added tagsKey configuration option to be able to change the key name for tags.
  • Added ability to remove log level and tags from the outputted log JSON.
  • Added addLevel() method to quickly add a custom log level to an instance of LambdaLog.
  • Tags can now be functions that return a dynamic tag for log messages.
  • Tags now have variable support.
  • Tags that are null, undefined or "" are now removed from the tags array.
  • Metadata that contains Error objects are now automatically converted to a plain object.

Breaking Changes:

  • All of the private properties of both the LambdaLog and LogMessage classes are stored using Symbols. This may break some advanced uses of Lambda Log from version 2.
  • Tags no longer contain any default, built-in tags and are empty by default.
  • Some of the properties of LogMessage have been moved from the constructor to their own getter functions.

Documentation

Documentation for Lambda Log has moved to our new website.

Tests

See Development Documentation.

Contributing

See Contributing Documentation.

License

MIT License. See License in the repository.

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Kyle Ross
💻 📖 🚧
Jonathan Goldwasser
💻 🐛
Gabriel
🤔
sh1n1chi8acker
🐛
Matt Nagi
📖
nickcox
📖
Tim Schmidt
💻

Marius Tolzmann
🐛
AndresQ
🤔
Mike Fogel
🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

changelog

3.1.0 (2021-10-14)

Bug Fixes

  • add redirect to github pages for old site to new domain (bae1b15)
  • add step to workflow to purge expired artifacts (f051daf)

Features

  • deprecate addLevel() method (86897b1)
  • deprecate custom log levels (abba03a)
  • rebuild site using Next.js with new design and more documentation (4304c1d)

3.0.2 (2021-10-01)

Bug Fixes

  • skip adding a toJSON method to errors that already have one (#61) (5b03656)

3.0.1 (2021-09-27)

Bug Fixes

  • include error name in metadata (5a1214c), closes #52

3.0.0 (2021-04-12)

Bug Fixes

  • add .npmignore file to help reduce the size of the package (c21bd7f)
  • add .npmignore file to help reduce the size of the package (9ccdc69)
  • do not use husky when on a CI environment (a17ac76)
  • reverse the check for LAMBDALOG_SILENT env variable (95828b1)
  • reverse the check for LAMBDALOG_SILENT env variable (5ab6dc5)

Code Refactoring

  • move message.tags to a getter and setter (201a6fe)

Features

  • add ability for tags to be functions (459380f)
  • add ability for tags to be functions (87ea24d)
  • add ability to change the key names of the message output (4a71909)
  • add ability to change the key names of the message output (bc1169b)
  • add new method addLevel() to LambdaLog (9fde2e3)
  • add new method addLevel() to LambdaLog (f7dbfd0)
  • add new options levelKey, messageKey, and tagsKey (bb5ba70)
  • add new options levelKey, messageKey, and tagsKey (4d10968)
  • add new website! (44a15dc)
  • add new website! (9aa6e2e)
  • add symbols for referencing private properties in LogMessage (f4b1c99)
  • add symbols for referencing private properties in LogMessage (beb5e39)
  • add symbols to reference certain private properties (b502366)
  • add symbols to reference certain private properties on LogMessage class (952b62d)
  • convert Errors in metadata to plain objects #31 (f55d474)
  • convert Errors in metadata to plain objects #31 (576052a)
  • remove default tags and add tag variable support #29 (a43b0ae)
  • remove default tags and add tag variable support #29 (ae686ef)
  • set node engine to >= 10.0.0 (0b5e564)
  • set node engine to >= 10.0.0 (2d022ec)
  • switch from travis to github actions (6ca053f)
  • use jest for testing and coverage (216141d)
  • internal: add function to stub errors with a toJSON method (b5e3dbe)
  • switch from travis to github actions (f2d418e)
  • use jest for testing and coverage (fafed5d)
  • internal: add function to stub errors with a toJSON method (d0707bd)

BREAKING CHANGES

  • There are no longer any built-in tags added to the tags array for each log message.
  • message.tags is no longer a property of the LogMessage class that can be directly changed.
  • Whenever an Error object is passed into the metadata for a log message, it will automatically be converted to a plain object as stringifying the an Error object will always yield {}.
  • Previously you could directly access the private properties of LogMessage. In order to add some integrity, they are no longer using standard property names starting with an underscore and are instead referenced using symbols instead. For advanced usage, these symbols are exported as a static property on the LogMessage class under LogMessage.symbols.
  • Previously you could directly access the private properties of LambdaLog. In order to add some integrity, they are no longer using standard property names starting with an underscore and are instead referenced using symbols instead. For advanced usage, these symbols are exported as a static property on the LambdaLog class under LambdaLog.symbols.

2.4.0 (2020-05-15)

Bug Fixes

  • check for "falsey" values for LAMBDALOG_SILENT (187f755)

Features

  • allow globally overriding silent via env var LAMBDALOG_SILENT (aecbfba)

2.3.1 (2019-09-03)

Bug Fixes

2.3.0 (2019-06-21)

Bug Fixes

  • add .DS_Store to gitignore (968bd50)

Features

  • add log.result() method (3b98ec3)

Performance Improvements

  • switch to fast-safe-stringify to increase performance (3f5fa59)

2.2.0 (2019-03-20)

Features

  • logmessage: allow overriding LogMessage (8a867ac)

2.1.0 (12/19/2018)

  • BREAKING: Removed stdoutStream and stderrStream options.
  • NEW: Added logHandler option which takes a console-like object to send logs through. (#11)

2.0.1 (12/7/2018)

  • Fix console logging pointing to global console instead of custom console instance for streaming. (@sh1n1chi8acker - #10)
  • Update mocha to v5.2.0
  • Added package-lock.json to .gitignore as it's not needed for this module.

2.0.0 (7/15/2018)

The new major release for lambda-log which contains many new extensibility features and a handful of new usability features. There are a few breaking changes from version 1.4.0 to keep in mind when migrating. All breaking changes will be noted in the changelog below:

Internal/Module Changes

  • Moved LambdaLog class out of index.js into lib/LambdaLog.js for organization purposes.
  • NEW: Utilize console module (native Node) instead of the global console object for logging. This allows more control of where logs are redirected to for custom advanced integrations.
  • NEW: Log messages are now an instance of the LogMessage class which allows custom methods and better control over log messages.

LambdaLog Class/Configuration

  • NEW: Added ability to configure the logger via the constructor (#3).
  • NEW: Added ability to configure the log levels and methods via the constructor.
  • NEW: Added stdoutStream and stderrStream configuration options to configure the desired output of log messages. By default it redirects to process.stdout and process.stderr.
  • NEW: Added dynamicMeta configuration option which will allow dynamic metadata to be added to each log on creation.
  • NEW: Added replacer configuration option for JSON.stringify.
  • BREAKING: Static method isError() has been moved to the LogMessage class and is no longer accessible in the LambdaLog class.

Logging Functions

  • NEW: All log functions now accept an array of tags to append to a log.
  • FIX: Metadata passed into a log function will now be wrapped in a plain object if the provided value is not an object.
  • BREAKING: All log functions now return an instance of LogMessage instead of a plain log object which allows directly calling additional methods of LogMessage (chaining). See documentation for more information.

Events

  • BREAKING: The log event now provides an instance of LogMessage instead of a plain object.

Misc.

  • Updated tests.
  • Updated documentation/readme.

1.5.0 (7/15/2018)

  • Added json-stringify-safe to prevent issues with circular references. (@jogold)

1.4.0 (5/31/2018)

  • New: Added log.assert().
  • Updated README formatting.
  • Added Travis for automated test running.

1.3.0 (1/2/2018)

  • New: Added _logLevel as property to logged messages to allow easier searching in Cloudwatch Logs.
  • Added missing tests.

1.2.1 (5/11/2017)

  • Fix issue with console.debug not existing in Lambda.

1.2.0 (5/4/2017)

  • Breaking Change: log event now returns object containing level, log and meta.

1.1.0 (5/2/2017)

  • New: Added log.debug() method for debug messages.
  • New: Added config.debug to enable and disable debug log messages (default is false).

1.0.0 (4/11/2017)

  • Initial release