standard-log

standard-log is a powerful and extensible logging library.

Key features

• Support micro-app with isolated log system.
• Create multiple loggers for different part of your application.
• Provide multiple log levels out of the box.
• Support custom log levels.
• Three levels of log level controls: log system, logger, and log method.
• Send logs to multiple reporters, e.g. console, file, memory, or remote service.
• Custom formatting and filtering for each reporter.
• Security focus. After the system is created, it cannot be changed.

Usage

There are two ways to use standard-log: global or standalone.

Standalone is the preferred way. You call createStandardLog() to get an isolated log system.

import { createStandardLog } from 'standard-log'

const standardLog = createStandarLog(/* options */)

const log = standardLog.getLogger('my-app')

log.error('error message')
log.warn('warn message')
log.info('info message')
// by default debug() will not be printed
// because production mode defaults log level to `info`
log.debug('debug message')

// If the message is consume resource to generage,
// you can use `log.on()` so that it will be called only
// if the level is met.
log.on(logLevels.trace, () => prettify(someValue))
Copy

(above is logged with standard-log-color)

You can configure a logger by doing getLogger(id, options):

options.level: number:

Log level of this logger.

options.writeTo: string | RegExp | ((reporterId: string) => boolean):

Only log to specific reporter(s).

Log Level

standard-log log level defaults to logLevels.info. It comes with many log levels out of the box:

log.emergency('msg')
log.alert('msg')
log.critical('msg')
log.error('msg')
log.warn('msg')
log.notice('msg')
log.info('msg')
log.debug('msg')
log.trace('msg')
log.planck('msg')
Copy

When sending logs to console, they are mapped to info, warn, error, and debug based on severity.

You can also add your own custom levels:

import { createStandardLog } from 'standard-log'

const standardLog = createStandardLog({
  customLevels: {
    'important': logLevel.warn + 1,
    'silly': logLevel.debug + 1
  }
})

const log = standardLog.getLogger('custom')
log.important('this is an important message')
log.silly('oh silly')
Copy

Reporters

Besides printing the logs to console, you can use different reporters to save the logs in memory, file, service, or others.

import { createStandardLog, createConsoleLogReporter, createMemoryLogReporter } from 'standard-log'

createStandardLog({
  reporters: [createConsoleLogReporter(), createMemoryLogReporter()]
})
Copy

Some reporters allow you to format the logs and/or filter them. Using the console log reporter as an example:

import { createConsoleLogReporter } from 'standard-log'

createConsoleLogReporter({
  formatter: (entry) => [...],
  filter: (entry) => entry.args.every(arg => arg !== 'secret')
})
Copy

Here are some additional reporters:

• standard-log-color
• standard-log-file (TODO)
• standard-log-syslog

Suppress log

You can temporarily suppress logs by suppressLogs(). This allows you to disable downstream logs to reduce log noises.

import { getLogger, suppressLogs } from 'standard-log'

const log = getLogger('some logger')

suppressLogs(() => log.info('not logged'), log)
Copy

Testing

During test, you should use createStandardLogForTest which includes a MemoryReporter to capture the logs.

import { createStandardLogForTest } from 'standard-log/testing'

test('your test', () => {
  const standardLog = createStandardLogForTest()
  yourApp.standardLog = standardLog

// do your thing...

  const messages = standardLog.reporter.getLogMessage() // or getLogMessageWithLevel()
  // validate the message if you want to
})
Copy

Global usage

You can also call getLogger() to get a logger and log away:

import { getLogger } from 'standard-log'

const log = getLogger('my-lib')
log.info('log away')
Copy

It internally creates a global instance of standard-log. To configure this global instance, use configGlobal():

import { configGlobal } from 'standard-log'

configGlobal({ logLevel: logLevels.info, reporters: [ ... ] })
Copy

This global instance does not support custom levels. And it will emit a warning when configGlobal() is called more than once. Typically, configGlobal() should be called by the application, and it happens only once. But in micro-app situation, the library can be shared, and each application can call configGlobal()

In general, using this global instance should be avoided. It is the main driving force for 9.0.