---
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).