or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tool.mdcolorization.mdconfiguration.mdcustom-prettifiers.mdindex.mdmessage-formatting.mdprettifier-factory.mdstream-transport.md
tile.json

tessl/npm-pino-pretty

Prettifier for Pino log lines

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pino-pretty@13.1.x

To install, run

npx @tessl/cli install tessl/npm-pino-pretty@13.1.0

index.mddocs/

Pino Pretty

Pino Pretty is a specialized log formatting tool that transforms ndjson-formatted log lines, particularly from the Pino logging library, into human-readable, prettified output for development environments. It offers comprehensive formatting capabilities including colorized output with terminal escape sequences, customizable message templates and field mapping, flexible timestamp translation with timezone support, and fine-grained control over displayed log properties through inclusion/exclusion filters.

Package Information

  • Package Name: pino-pretty
  • Package Type: npm
  • Language: JavaScript (CommonJS with TypeScript definitions)
  • Installation: npm install pino-pretty

Core Imports

const pinoPretty = require('pino-pretty');

ESM (via TypeScript definitions):

import pinoPretty from 'pino-pretty';
import { build, prettyFactory, colorizerFactory, isColorSupported } from 'pino-pretty';

Basic Usage

As a Pino Transport

const pino = require('pino');
const logger = pino({
  transport: {
    target: 'pino-pretty',
    options: {
      colorize: true,
      translateTime: 'HH:MM:ss',
      ignore: 'pid,hostname'
    }
  }
});

logger.info('hello world');
// Output: [10:30:45] INFO: hello world

As a Stream

const pino = require('pino');
const pretty = require('pino-pretty');

const stream = pretty({
  colorize: true,
  translateTime: 'SYS:standard',
  ignore: 'pid,hostname'
});

const logger = pino(stream);
logger.info('hello world');

CLI Usage

node app.js | pino-pretty --colorize --translateTime

Architecture

Pino Pretty is built around several key components:

  • Transform Stream: Main build function creates a Node.js Transform stream that processes log lines
  • Prettifier Factory: Core prettyFactory function produces a stateless prettifier function
  • Colorizer System: Separate color management with support for custom color schemes
  • Parser Pipeline: Secure JSON parsing with passthrough for non-JSON lines
  • Formatting Engine: Modular prettification of time, level, metadata, message, and objects
  • CLI Tool: Full-featured command-line interface with config file support

Capabilities

Stream and Transport Creation

Creates a transform stream for prettifying Pino logs, supporting both direct streaming and Pino v7+ transport protocol.

/**
 * Constructs a prettifier and a transform stream for prettifying logs
 * @param opts - Configuration options
 * @returns Transform stream with OnUnknown interface
 */
function build(opts?: PrettyOptions): PrettyStream;

// Aliases for the same function
const PinoPretty = build;
const defaultExport = build;

Stream and Transport Creation

Prettifier Factory

Creates a stateless prettifier function for direct log transformation without streams.

/**
 * Creates a function that accepts log data and produces prettified strings
 * @param options - Configuration for the prettifier
 * @returns Function that transforms log objects/strings into prettified strings
 */
function prettyFactory(options: PrettyOptions): (inputData: string | object) => string;

Prettifier Factory

Colorization

Provides terminal colorization for log levels and messages with custom color scheme support.

/**
 * Factory function to create a colorizer for log levels and messages
 * @param useColors - Enable terminal colors (default: false)
 * @param customColors - Array of [level, colorName] tuples
 * @param useOnlyCustomProps - Only use custom colors without fallback (default: false)
 * @returns Colorizer function with message/property colorization methods
 */
function colorizerFactory(
  useColors?: boolean,
  customColors?: [number, string][],
  useOnlyCustomProps?: boolean
): ColorizerFunc;

interface ColorizerFunc {
  (level: number | string, opts?: {
    customLevels?: { [level: number]: string };
    customLevelNames?: { [name: string]: number };
  }): string;
  message(input: string | number): string;
  greyMessage(input: string | number): string;
  property(input: string | number): string;
  colors: Colorette;
}

/**
 * Boolean indicating if the current terminal supports colors
 */
const isColorSupported: boolean;

Colorization

Configuration Options

Comprehensive configuration interface controlling all aspects of log prettification.

interface PrettyOptions {
  // Display options
  colorize?: boolean;
  colorizeObjects?: boolean;
  crlf?: boolean;
  hideObject?: boolean;
  singleLine?: boolean;
  levelFirst?: boolean;

  // Key mapping
  messageKey?: string;
  levelKey?: string;
  levelLabel?: string;
  timestampKey?: string;
  errorLikeObjectKeys?: string[];

  // Filtering
  minimumLevel?: string | number;
  ignore?: string;
  include?: string;

  // Formatting
  translateTime?: boolean | string;
  messageFormat?: false | string | MessageFormatFunc;
  errorProps?: string;

  // Custom levels and colors
  customLevels?: string | object;
  customColors?: string | object;
  useOnlyCustomProps?: boolean;
  customPrettifiers?: Record<string, Prettifier> & { level?: Prettifier };

  // Output options
  destination?: string | number | DestinationStream | NodeJS.WritableStream;
  sync?: boolean;
  append?: boolean;
  mkdir?: boolean;
}

Configuration Options

Custom Prettifiers

Extensibility system for customizing the formatting of specific log properties.

/**
 * Custom prettifier function for specific log properties
 * @param inputData - The value of the property to prettify
 * @param key - The property name
 * @param log - The complete log object for context
 * @param extras - Additional context including colors and labels
 * @returns Prettified string representation
 */
type Prettifier = (
  inputData: string | object,
  key: string,
  log: object,
  extras: PrettifierExtras
) => string;

interface PrettifierExtras {
  colors: Colorette;
  label: string;
  labelColorized: string;
}

Custom Prettifiers

Message Formatting

Flexible message templating system with token substitution and conditional blocks.

/**
 * Function to customize message output
 * @param log - The log object being processed
 * @param messageKey - The key containing the message
 * @param levelLabel - The level label string
 * @param extras - Additional context including colors
 * @returns Formatted message string
 */
type MessageFormatFunc = (
  log: LogDescriptor,
  messageKey: string,
  levelLabel: string,
  extras: PrettifierExtras
) => string;

type LogDescriptor = Record<string, unknown>;

Message Formatting

CLI Tool

Command-line interface for prettifying Pino logs with extensive options and config file support.

CLI Tool

Constants

// Default date format patterns
const DATE_FORMAT = 'yyyy-mm-dd HH:MM:ss.l o';
const DATE_FORMAT_SIMPLE = 'HH:MM:ss.l';

// Default key names
const MESSAGE_KEY = 'msg';
const LEVEL_KEY = 'level';
const LEVEL_LABEL = 'levelLabel';
const TIMESTAMP_KEY = 'time';
const ERROR_LIKE_KEYS = ['err', 'error'];

// Standard Pino levels
const LEVELS = {
  default: 'USERLVL',
  60: 'FATAL',
  50: 'ERROR',
  40: 'WARN',
  30: 'INFO',
  20: 'DEBUG',
  10: 'TRACE'
};

const LEVEL_NAMES = {
  fatal: 60,
  error: 50,
  warn: 40,
  info: 30,
  debug: 20,
  trace: 10
};

// Standard logger metadata keys
const LOGGER_KEYS = [
  'pid', 'hostname', 'name', 'level',
  'time', 'timestamp', 'caller'
];

Types

type PrettyStream = Transform & OnUnknown;

type Colorette = {
  isColorSupported: boolean;
  reset: (str: string) => string;
  bold: (str: string) => string;
  dim: (str: string) => string;
  italic: (str: string) => string;
  underline: (str: string) => string;
  inverse: (str: string) => string;
  hidden: (str: string) => string;
  strikethrough: (str: string) => string;
  black: (str: string) => string;
  red: (str: string) => string;
  green: (str: string) => string;
  yellow: (str: string) => string;
  blue: (str: string) => string;
  magenta: (str: string) => string;
  cyan: (str: string) => string;
  white: (str: string) => string;
  gray: (str: string) => string;
  bgBlack: (str: string) => string;
  bgRed: (str: string) => string;
  bgGreen: (str: string) => string;
  bgYellow: (str: string) => string;
  bgBlue: (str: string) => string;
  bgMagenta: (str: string) => string;
  bgCyan: (str: string) => string;
  bgWhite: (str: string) => string;
};