--- title: Logging --- import EnvBadges from '@theme/EnvBadges'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; Lightweight level based logging system. ## Installation ```bash yarn add @boost/log ``` ```bash pnpm add @boost/log ``` ```bash npm install @boost/log ``` ## Environment variables - `BOOSTJS_LOG_DEFAULT_LEVEL` ([`LogLevel`](/api/log#LogLevel)) - The default log level to use when calling the logger function stand alone (the usage examples below). Defaults to the lowest level, `log`. - `BOOSTJS_LOG_MAX_LEVEL` ([`LogLevel`](/api/log#LogLevel)) - The maximum level, based on priority, to write to a stream. All levels higher than the maximum will be ignored. Defaults to allowing all levels. ## Logging Logging is based around the concept of a "logger", which provides a set of functions of severity levels to log with. Logs are written to one or many provided transports -- or `console` if not defined. To begin, instantiate a logger with [`createLogger`](/api/log/function/createLogger), which returns a function that can be used for standard level logging. ```ts import { createLogger } from '@boost/log'; const log = createLogger({ name: 'boost' }); log('Something has happened…'); ``` Each logging function requires a message string as the 1st argument, and an optional rest of arguments to interpolate into the message using [`util.format()`](https://nodejs.org/api/util.html#util_util_format_format_args). ```ts log('Name: %s %s', user.first_name, user.last_name); log('Object: %O', data); ``` If you would prefer to interact with a class instance, you may use the [`Logger`](/api/log/class/Logger) class. The major difference between the class and the function, is that the class only has 1 logging method, [`Logger#log()`](/api/log/class/Logger#log). ```ts import { Logger } from '@boost/log'; const logger = new Logger({ name: 'boost' }); logger.log({ level: 'info', message: 'Something else has happened…', }); ``` ### Options When creating a logger, a [`LoggerOptions`](/api/log/interface/LoggerOptions) object can be passed. The options _cannot_ be customized after the fact. ```ts import chalk from 'chalk'; import { createLogger, StreamTransport } from '@boost/log'; const log = createLogger({ name: 'boost', labels: { error: chalk.bgRed.black.bold(' FAIL '), }, transports: [new StreamTransport({ levels: ['error'], stream: process.stderr })], }); ``` ### Log levels There are 5 distinct logging levels outside the standard level, each represented as a unique function on the logger instance. The levels in order of **priority** are `trace`, `debug`, `info`, `warn`, and `error`. Each function requires a message as the 1st argument, and an optional rest of arguments to interpolate into the message. ```ts log.trace('Code path hit?'); log.debug('What is going on here?'); log.info('Systems are stable'); log.warn('Something is definitely going on…'); log.error('Systems are down! %s', error.message); ``` ### Silencing output By default, all logged messages are immediately written to the configured transports. To silence output and disable writes, call the [`logger.disable()`](/api/log/interface/LoggerFunction#disable) function, and to re-enable, call [`logger.enable()`](/api/log/interface/LoggerFunction#enable). ```ts log.disable(); // Will not write! log.debug('Something is broken!'); ``` > Messages that are logged while silenced are _lost_ and are _not_ buffered. ## Formats All logs are represented as an object, known as a [`LogItem`](/api/log/interface/LogItem). These items contain metadata about the environment, the logger, and the current log message. Before an item is written to a transport, it must be formatted from an object into a string. This can be done on a per transport basis using the [`format`](/api/log/interface/TransportOptions#format) option, like so. ```ts import { ConsoleTransport, formats } from '@boost/log'; const transport = new ConsoleTransport({ format: (item) => `${item.level} ${item.message}`, // Or a pre-built format format: formats.json, }); ``` Boost provides formats by default, all of which are pre-configured into each built-in transport. Feel free to use the [built-in formats](/api/log/namespace/formats), or customize your own! ## Metadata Sometimes additional metadata may be required that is not found within the pre-defined log item fields. Metadata can be defined on the logger using an object, which is then passed to all log items. ```ts const log = createLogger({ name: 'boost', metadata: { locale: 'en', region: 'eu', }, }); ``` It can also be defined per log by passing an object as the 1st argument. Metadata defined at this level will override the logger metadata. ```ts log({ locale: 'de' }, "What's going on?"); ``` > Fields `name`, `host`, and `pid` are reserved names and cannot be used. ## Transport types There are multiple types of transports that can be used within a logger, all of which support a [`TransportOptions`](/api/log/interface/TransportOptions) object. Some transports support additional options, so please refer to their types. ### ConsoleTransport The [`ConsoleTransport`](/api/log/class/ConsoleTransport) logs messages to the native `console` and its corresponding level. This is the default transport when no transports are defined. ```ts import { ConsoleTransport } from '@boost/log'; const transport = new ConsoleTransport(); ``` ### StreamTransport The [`StreamTransport`](/api/log/class/StreamTransport) logs messages to any writeable stream or an object that defines a [`write()`](/api/log/interface/Writable) method. Additional [`StreamTransportOptions`](/api/log/interface/StreamTransportOptions) options may be provided. ```ts import { StreamTransport } from '@boost/log'; const transport = new StreamTransport({ levels: ['error', 'warn'], stream: process.stderr, }); ``` ### FileTransport The [`FileTransport`](/api/log/class/FileTransport) appends and logs messages to a file at the defined path. Will automatically rotate files when a max file size is met. Additional [`FileTransportOptions`](/api/log/interface/FileTransportOptions) options may be provided. ```ts import { FileTransport } from '@boost/log'; const transport = new FileTransport({ levels: ['error'], path: '/var/log/error.log', }); ``` ### RotatingFileTransport The [`RotatingFileTransport`](/api/log/class/RotatingFileTransport) is like [`FileTransport`](/api/log/class/FileTransport), but also rotates files based on timestamps and a chosen periodic interval. Additional [`RotatingFileTransportOptions`](/api/log/interface/RotatingFileTransportOptions) options may be provided. ```ts import { RotatingFileTransport } from '@boost/log'; const transport = new RotatingFileTransport({ levels: ['error'], path: '/var/log/error.log', rotation: 'daily', }); ``` ## Test utilities A handful of [Vitest](https://vitest.dev/) utilities are available in the `@boost/log/test` module. [View the API for a full list](/api/log-test).