pino-pretty

What is pino-pretty?

The pino-pretty npm package is a module that can be used to format logs produced by Pino, a Node.js logging library. It takes raw log lines in JSON format and transforms them into a more human-readable form. This is particularly useful during development when you need to quickly understand log output.

What are pino-pretty's main functionalities?

Pretty Printing

This feature allows you to format your logs in a more readable way, with options such as colorization for different log levels.

const pino = require('pino');
const pretty = require('pino-pretty');
const stream = pretty({ colorize: true });
const logger = pino(stream);
logger.info('This is a pretty-printed log message.');

Custom Log Formatting

Pino-pretty allows for custom log formatting, including options to translate timestamps and ignore certain fields.

const pino = require('pino');
const pretty = require('pino-pretty');
const stream = pretty({
  translateTime: 'SYS:standard',
  ignore: 'pid,hostname'
});
const logger = pino(stream);
logger.info('Custom formatted log message.');

Integration with Pino Logger

Pino-pretty can be seamlessly integrated with Pino logger to provide pretty-printing capabilities directly within the logger configuration.

const pino = require('pino');
const logger = pino({
  prettyPrint: {
    colorize: true
  }
});
logger.info('Integrated pino-pretty with Pino logger.');

Other packages similar to pino-pretty

bunyan

Bunyan is a simple and fast JSON logging library for node.js services. It comes with a CLI tool for pretty-printing bunyan log output. Compared to pino-pretty, Bunyan provides its own logging capabilities, whereas pino-pretty is specifically designed to format Pino logs.

winston

Winston is a multi-transport async logging library for Node.js. It supports custom formatting and multiple logging transports. Unlike pino-pretty, which is focused on pretty-printing, Winston offers a broader set of logging features including transports for logging to various outputs.

morgan

Morgan is an HTTP request logger middleware for Node.js. It can format logs in predefined or custom formats. While morgan is used for logging HTTP requests in web applications, pino-pretty is used for general purpose log formatting.

README

pino-pretty

This module provides a basic ndjson formatter. If an incoming line looks like it could be a log line from an ndjson logger, in particular the Pino logging library, then it will apply extra formatting by considering things like the log level and timestamp.

A standard Pino log line like:

{"level":30,"time":1522431328992,"msg":"hello world","pid":42,"hostname":"foo","v":1}

Will format to:

[1522431328992] INFO (42 on foo): hello world

Example

Using the example script from the Pino module, and specifying that logs should be colored and the time translated, we can see what the prettified logs will look like:

Install

$ npm install -g pino-pretty

Usage

It is recommended to use pino-pretty with pino by piping output to the CLI tool:

node app.js | pino-pretty

CLI Arguments

• --colorize (-c): Adds terminal color escape sequences to the output.
• --crlf (-f): Appends carriage return and line feed, instead of just a line feed, to the formatted log line.
• --errorProps (-e): When formatting an error object, display this list of properties. The list should be a comma-separated list of properties Default: ''.
• --levelFirst (-l): Display the log level name before the logged date and time.
• --errorLikeObjectKeys (-k): Define the log keys that are associated with error like objects. Default: err,error.
• --messageKey (-m): Define the key that contains the main log message. Default: msg.
• --levelKey (--levelKey): Define the key that contains the level of the log. Default: level.
• --levelLabel (-b): Output the log level using the specified label. Default: levelLabel.
• --messageFormat (-o): Format output of message, e.g. {levelLabel} - {pid} - url:{request.url} will output message: INFO - 1123 - url:localhost:3000/test Default: false
• --timestampKey (-a): Define the key that contains the log timestamp. Default: time.
• --translateTime (-t): Translate the epoch time value into a human-readable date and time string. This flag also can set the format string to apply when translating the date to a human-readable format. For a list of available pattern letters, see the dateformat documentation.
  • The default format is yyyy-mm-dd HH:MM:ss.l o in UTC.
  • Require a SYS: prefix to translate time to the local system's time zone. A shortcut SYS:standard to translate time to yyyy-mm-dd HH:MM:ss.l o in system time zone.
• --search (-s): Specify a search pattern according to jmespath.
• --ignore (-i): Ignore one or several keys, nested keys are supported with each property delimited by a dot character (.), keys may be escaped to target property names that contains the delimiter itself: (-i time,hostname,req.headers,log\\.domain\\.corp/foo)
• --hideObject (-H): Hide objects from output (but not error object)
• --singleLine (-S): Print each log message on a single line (errors will still be multi-line)
• --config: Specify a path to a config file containing the pino-pretty options. pino-pretty will attempt to read from a .pino-prettyrc in your current directory (process.cwd) if not specified

Programmatic Integration

We recommend against using pino-pretty in production and highly recommend installing pino-pretty as a development dependency.

When installed, pino-pretty will be used by pino as the default prettifier.

Install pino-pretty alongside pino and set the prettyPrint option to true:

const pino = require('pino')
const logger = pino({
  prettyPrint: true
})

logger.info('hi')

The prettyPrint option can also be an object containing pretty-print options:

const pino = require('pino')
const logger = pino({
  prettyPrint: { colorize: true }
})

logger.info('hi')

See the Options section for all possible options.

Options

pino-pretty exports a factory function that can be used to format log strings. This factory function is used internally by Pino, and accepts an options argument with keys corresponding to the options described in CLI Arguments:

{
  colorize: colorette.options.enabled, // --colorize
  crlf: false, // --crlf
  errorLikeObjectKeys: ['err', 'error'], // --errorLikeObjectKeys
  errorProps: '', // --errorProps
  levelFirst: false, // --levelFirst
  messageKey: 'msg', // --messageKey
  levelKey: 'level', // --levelKey
  messageFormat: false, // --messageFormat
  timestampKey: 'time', // --timestampKey
  translateTime: false, // --translateTime
  search: 'foo == `bar`', // --search
  ignore: 'pid,hostname', // --ignore
  hideObject: false, // --hideObject
  singleLine: false, // --singleLine
  customPrettifiers: {}
}

The colorize default follows colorette.options.enabled.

customPrettifiers option provides the ability to add a custom prettify function for specific log properties. customPrettifiers is an object, where keys are log properties that will be prettified and value is the prettify function itself. For example, if a log line contains a query property, you can specify a prettifier for it:

{
  customPrettifiers: {
    query: prettifyQuery
  }
}
//...
const prettifyQuery = value => {
  // do some prettify magic
}

messageFormat option allows you to customize the message output. A template string like this can define the format:

{
  messageFormat: '{levelLabel} - {pid} - url:{request.url}'
}

This option can also be defined as a function with this prototype:

{
  messageFormat: (log, messageKey, levelLabel) => {
    // do some log message customization
    return customized_message;
  }
}

License

MIT License