Overview#

Introduction#

pino-zen is a colored log formatter for Pino JSON logs. Works as a Pino transport or a CLI pipe. It transforms Pino's structured JSON log output into human-readable, color-coded console output.

Key Information#

• Current Version: 3.2.0
• License: MIT
• Author: James Talton
• Node.js Requirement: Node.js >=18
• Package Type: ES Module

Installation#

Install via npm:

npm install pino-zen # project dependency
npm install -g pino-zen # global CLI
npx pino-zen # run without installing

Main Features#

1. Pino Transport Integration#

Can be used directly as a Pino transport for colored console output alongside other logging targets like file outputs. This allows you to simultaneously write logs to files and display formatted output in the console.

2. Module Mode#

Prepends color-coded, right-aligned module names to logs, making it especially useful for microservices or mono-repos to distinguish logs from different components. Module names are automatically tracked and right-aligned based on the longest module name encountered during the process lifecycle.

3. Field Suppression#

Allows hiding specific fields (like pid and hostname) from the output using formatter options.

4. Custom Destination#

Supports writing to custom file paths or file descriptors instead of stdout.

5. CLI Pipe Mode#

Can be used as a command-line tool to pipe NDJSON log output through for formatting. The CLI binary is available as pino-zen.

How It Works#

pino-zen acts as a formatter/transport for Pino's structured JSON logs, converting them into colored, human-readable output. It uses pino-abstract-transport to implement a custom Pino transport, and uses chalk for terminal styling and sonic-boom for fast file writing.

Usage Examples#

As a Pino Transport#

Example from README:

import pino from "pino"

const logger = pino({
  transport: {
    target: "pino-zen",
  },
})

Multiple Targets#

const logger = pino({
  level: "debug",
  transport: {
    targets: [
      { target: "pino/file", options: { destination: "app.log" } },
      { target: "pino-zen" },
    ],
  },
})

Module Mode#

Example from README:

const logger = pino({
  transport: {
    target: "pino-zen",
    options: { module: "module" },
  }
})

logger.info({ module: "api" }, "request processed")
logger.info({ module: "auth" }, "user verified")

Output:

 [api] INFO request processed
[auth] INFO user verified

CLI Usage#

Example from README:

node app.js | pino-zen
node app.js | npx pino-zen

Technical Details#

• Entry Points: Main library at ./lib/pino-zen.js with TypeScript definitions at ./lib/pino-zen.d.ts
• Dependencies:
  • chalk ^5.6.2 - terminal styling
  • pino-abstract-transport ^3.0.0 - Pino transport abstraction
  • sonic-boom ^4.2.1 - fast file writing
  • split2 ^4.2.0 - stream splitting