Text formatters

A text formatter is a function that formats a log record into a string. LogTape has three built-in sinks that can take a text formatter:

• stream sink
• file sink
• rotating file sink

Of course, you can write your own sinks that take a text formatter.

Built-in text formatters

LogTape provides three built-in text formatters:

Default text formatter

defaultTextFormatter formats a log record into a string with a simple format. It renders the timestamp, the log level, the message, and the prettified values embedded in the message.

It formats log records like this:

2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!

ANSI color formatter

This API is available since LogTape 0.5.0.

ansiColorFormatter formats a log record into a string with a simple format and ANSI colors. It renders the timestamp, the log level, the message, and the prettified values embedded in the message.

It formats log records like this:

JSON Lines formatter

This API is available since LogTape 0.11.0.

jsonLinesFormatter formats log records as JSON Lines (also known as Newline-Delimited JSON or NDJSON). Each log record is rendered as a JSON object on a single line, which is a common format for structured logging.

It formats log records like this:

{"@timestamp":"2023-11-14T22:13:20.000Z","level":"INFO","message":"Hello, world!","logger":"my.logger","properties":{"key":"value"}}

Configuring text formatters

This API is available since LogTape 0.6.0.

You can customize the built-in text formatters with a TextFormatterOptions or an AnsiColorFormatterOptions object without building a new text formatter from scratch.

Default text formatter

You can customize the default text formatter by calling the getTextFormatter() function with a TextFormatterOptions object. Customizable options include:

timestamp

The timestamp format. This can be one of the following:

• "date-time-timezone": The date and time with the full timezone offset (e.g., 2023-11-14 22:13:20.000 +00:00).
• "date-time-tz": The date and time with the short timezone offset (e.g., 2023-11-14 22:13:20.000 +00).
• "date-time": The date and time without the timezone offset (e.g., 2023-11-14 22:13:20.000).
• "time-timezone": The time with the full timezone offset but without the date (e.g., 22:13:20.000 +00:00).
• "time-tz": The time with the short timezone offset but without the date (e.g., 22:13:20.000 +00).
• "time": The time without the date or timezone offset (e.g., 22:13:20.000).
• "date": The date without the time or timezone offset (e.g., 2023-11-14).
• "rfc3339": The date and time in RFC 3339 format (e.g., 2023-11-14T22:13:20.000Z).
• "none" or "disabled": No display

Alternatively, this can be a function that accepts a timestamp and returns a string.

The default is "date-time-timezone".

level

The log level format. This can be one of the following:

• "ABBR": The log level abbreviation in uppercase (e.g., INF).
• "FULL": The full log level name in uppercase (e.g., INFO).
• "L": The first letter of the log level in uppercase (e.g., I).
• "abbr": The log level abbreviation in lowercase (e.g., inf).
• "full": The full log level name in lowercase (e.g., info).
• "l": The first letter of the log level in lowercase (e.g., i).

Alternatively, this can be a function that accepts a log level and returns a string.

The default is "ABBR".

category

The separator between the category names.

For example, if the separator is "·", the category ["a", "b", "c"] will be formatted as "a·b·c".

The default separator is "·".

If this is a function, it will be called with the category array and should return a string, which will be used for rendering the category.

value

The format of the embedded values.

A function that renders a value to a string. This function is used to render the values in the log record. The default is util.inspect() in Node.js/Bun and Deno.inspect() in Deno.

format

How those formatted parts are concatenated.

A function that formats the log record. This function is called with the formatted values and should return a string. Note that the formatted should not include a newline character at the end.

By default, this is a function that formats the log record as follows:

2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!

ANSI color formatter

You can customize the ansiColorFormatter by calling the getAnsiColorFormatter() function with an AnsiColorFormatterOptions object. Customizable options include:

timestamp

The timestamp format. The available options are the same as the timestamp option of the default text formatter.

The default is "date-time-tz".

timestampStyle

The ANSI style for the timestamp. "dim" is used by default.

timestampColor

The ANSI color for the timestamp. No color is used by default.

level

The log level format. The available options are the same as the level option of the default text formatter.

The default is "ABBR".

levelStyle

The ANSI style for the log level. "bold" is used by default.

levelColors

The ANSI colors for the log levels. The default colors are as follows:

• "debug": "blue"
• "info": "green"
• "warning": "yellow"
• "error": "red"
• "fatal": "magenta"

category

The separator between the category names. Behaves the same as the category option of the default text formatter.

The default separator is "·".

categoryStyle

The ANSI style for the category. "dim" is used by default.

categoryColor

The ANSI color for the category. No color is used by default.

value

The format of the embedded values. Behaves the same as the value option of the default text formatter.

format

How those formatted parts are concatenated. Behaves the same as the format option of the default text formatter.

Text styles

The timestampStyle, levelStyle, and categoryStyle options can be one of the following:

• "bold"
• "dim"
• "italic"
• "underline"
• "strikethrough"
• null (no style)

Colors

The timestampColor, levelColors (an object with log levels as keys), and categoryColor options can be one of the following:

• "black"
• "red"
• "green"
• "yellow"
• "blue"
• "magenta"
• "cyan"
• "white"
• null (no color)

JSON Lines formatter

This API is available since LogTape 0.11.0.

You can customize the JSON Lines formatter by calling the getJsonLinesFormatter() function with a JsonLinesFormatterOptions object. Customizable options include:

categorySeparator

The separator between category names. For example, if the separator is ".", the category ["a", "b", "c"] will be formatted as "a.b.c".

The default separator is ".".

If this is a function, it will be called with the category array and should return a string or an array of strings, which will be used for rendering the category.

message

The message format. This can be one of the following:

• "template": The raw message template is used as the message.
• "rendered": The message is rendered with the values.

The default is "rendered".

properties

The properties format. This can be one of the following:

• "flatten": The properties are flattened into the root object.
• "prepend:<prefix>": The properties are prepended with the given prefix (e.g., "prepend:ctx_" will prepend ctx_ to each property key).
• "nest:<key>": The properties are nested under the given key (e.g., "nest:properties" will nest the properties under the properties key).

The default is "nest:properties".

Pattern-based redaction

This API is available since LogTape 0.10.0.

You can redact sensitive data in log records through pattern-based redaction by wrapping your text formatter with a redactByPattern() function from @logtape/redaction package:

import { getTextFormatter } from "@logtape/logtape";
import {
  EMAIL_ADDRESS_PATTERN,
  JWT_PATTERN,
  redactByPattern,
} from "@logtape/redaction";

const formatter = redactByPattern(getTextFormatter(), [
  EMAIL_ADDRESS_PATTERN,
  JWT_PATTERN,
]);

The above code will create a text formatter that redacts email addresses and JSON Web Tokens (JWTs) in log records. The redactByPattern() function takes a TextFormatter and an array of patterns, and returns a new TextFormatter that redacts the sensitive data matching those patterns.

For more information about it, see the Pattern-based redaction section.

Fully customized text formatter

A text formatter is just a function that takes a log record and returns a string. The type of a text formatter is TextFormatter:

export type TextFormatter = (record: LogRecord) => string;

If you want to build a text formatter from scratch, you can just write a function that takes a log record and returns a string. For example, the following function is a simple text formatter that formats log records into JSON Lines:

function jsonLinesFormatter(record: LogRecord): string {
  return JSON.stringify(record) + "\n";
}

Of course, you can use the built-in getJsonLinesFormatter() function for more sophisticated JSON Lines formatting with customizable options.