@omadi/neon

A logging library for Omadi javascript applications

Usage no npm install needed!

<script type="module">
  import omadiNeon from 'https://cdn.skypack.dev/@omadi/neon';
</script>

README

Neon

A logging library Omadi javascript application.

Use

import { Logger } from 'neon'

// Set log level.
process.env.LOG_LEVEL = 'warn'

// Initialize.
Logger.initialize({
  project: 'someProject',
  stage: 'someStage',
  requestId: 'requestId'
})

// Will appear:
Logger.error('The system is down.', otherDetails, ...)

// Won't appear - below logging level:
Logger.info('This thing happened you might want to know about.', theThing)

// Show all logs for a certain percentage of subsequent requests, even if below the log level:
process.env.LOG_REQUEST_PERCENT = 10

Logging functions:

Use one of these functions to output a log at the corresponding level. Any number of parameters may be logged. They will be put into the messages property as an array.

  • error (Warn about an unexpected, unrecoverable event. A stack trace is added to the log object.)
  • warn (Warn about an unexpected, but recoverable event.)
  • info (Notify about an expected event.)
  • debug (Always shows when NODE_ENV is dev. Output is not formatted.)
  • system (Keep track of common system-level events. Keep the chatter down here.)

Log Level

Log level is set through the LOG_LEVEL environment variable Options include:

  • none
  • error
  • warn
  • info
  • debug
  • status
  • all

Only logs generated with the function at or above the corresponding log level will be output via console.(error|warn|info|log).

If a requestId is present in a call to initialize, a percentage of requests will display all logs, regardless of log level. This percent is controlled by the LOG_REQUEST_PERCENT environment variable. Defaults to 5%. This behavior is ignored if NODE_ENV is set to dev

Other Functions

initialize

Accepts an object as a parameter. Use this to set context at the beginning of your application for all logs output during that execution. Useful for things like a correlation id or a reference id available in a lambda. It's recommended to include project, stage, and requestId.

setTrace

Allows a stack trace to be set in a different context than where the logs are generated, but more specific than when the logger is initialized. This is useful for getting context outside a promise where the logging is done. Can be called with false to reset to the default behavior.

runOnTest

No logs will be output in a test environment by default. This is determined by checking if the NODE_ENV environment variable is set to test. Call runOnTest with a boolean (default true) to toggle this behavior.

ENV

NODE_ENV

Setting NODE_ENV to dev will not format the output.