Public API

pino (default export / factory)

import pino from 'pino'

function pino(opts?: pino.LoggerOptions, stream?: pino.DestinationStream): pino.Logger
function pino(stream?: pino.DestinationStream): pino.Logger

The main factory function. Call it once at application startup to obtain a root logger. Pass an options object to configure level, serializers, redaction, and message key. The returned Logger instance is the object you call .info(), .error(), etc. on.

pino.destination

pino.destination(opts?: string | number | SonicBoomOpts): SonicBoom

Creates a high-throughput SonicBoom writable stream. Pass a file path, file descriptor (default 1 = stdout), or an options object with dest and sync. Use this when you need non-blocking writes or want to target a file instead of stdout.

logger.child

logger.child(bindings: Record<string, unknown>, options?: pino.ChildLoggerOptions): pino.Logger

Creates a new logger that inherits the parent's configuration and merges bindings into every log record it emits. Use child loggers to attach request-scoped context (e.g., requestId, userId) without manually threading fields through every log call.

pino.transport

pino.transport(opts: pino.TransportSingleOptions | pino.TransportMultiOptions): ThreadStream

Instantiates a worker-thread transport stream. Because Pino logs synchronously in the main thread and delegates I/O to the worker, this keeps the event loop free. Use it to write to remote sinks (Datadog, Elasticsearch, files) without blocking request handling.

Working examples

Scenario - Basic structured logging to stdout

Create a root logger and emit records at different levels. Fields from the options object appear on every line.

import pino from 'pino'

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  base: { pid: process.pid, service: 'api' },
  timestamp: pino.stdTimeFunctions.isoTime
})

logger.info('server started')
logger.warn({ port: 3000 }, 'listening on non-standard port')
logger.error(new Error('something broke'), 'unhandled error')

Scenario - Request-scoped child logger in an Express app

Attach a requestId to every log line within a single HTTP request without polluting the root logger.

import express from 'express'
import pino from 'pino'
import { randomUUID } from 'crypto'

const rootLogger = pino({ level: 'info' })
const app = express()

app.use((req, res, next) => {
  req.log = rootLogger.child({ requestId: randomUUID(), method: req.method, url: req.url })
  req.log.info('request received')
  next()
})

app.get('/health', (req, res) => {
  req.log.info('health check')
  res.json({ status: 'ok' })
})

app.listen(3000)

Scenario - Redacting sensitive fields

Prevent secrets from appearing in logs by configuring the redact option.

import pino from 'pino'

const logger = pino({
  level: 'info',
  redact: {
    paths: ['req.headers.authorization', 'user.password', '*.token'],
    censor: '[REDACTED]'
  }
})

logger.info({
  user: { id: 42, password: 's3cr3t' },
  req: { headers: { authorization: 'Bearer abc123' } }
}, 'login attempt')
// password and authorization are replaced with [REDACTED]

Scenario - Worker-thread transport writing to a file

Offload file I/O to a worker thread to avoid blocking the main event loop.

import pino from 'pino'

const transport = pino.transport({
  target: 'pino/file',
  options: { destination: '/var/log/app.log', mkdir: true }
})

const logger = pino({ level: 'info' }, transport)

logger.info({ startup: true }, 'application boot')
logger.debug('this line only appears if level is debug or lower')

File walkthrough

• pino.js - Root module; constructs the logger factory, wires symbols, serializers, level helpers, and exports pino.destination, pino.transport, pino.multistream, and pino.stdSerializers.
• pino.d.ts - TypeScript declarations for the entire public API including Logger, LoggerOptions, TransportOptions, redactOptions, and all helper types.
• browser.js - Alternate entry point for browser bundles; replaces Node streams with console.* calls and provides a subset of the redaction API using @pinojs/redact.
• file.js - Async helper that constructs a SonicBoom destination and awaits its ready event before returning; used by the pino/file transport target.
• bin.js - CLI wrapper; used when Pino is invoked via node bin.js or piped scripts.
• lib/levels.js - Level validation, numeric mappings, cache generation, and comparison helpers.
• lib/symbols.js - Private Symbol keys used to store internal state on logger instances without polluting the public interface.
• lib/tools.js - Utility factories: buildSafeSonicBoom, asChindings, buildFormatters, stringify, createArgsNormalizer.
• lib/proto.js - The logger prototype; defines .child(), .bindings(), .flush(), .isLevelEnabled(), and the level setter/getter.
• lib/redaction.js - Wraps @pinojs/redact to integrate path-based censoring into the serialization pipeline.
• lib/transport.js - Implements pino.transport(); spawns a ThreadStream worker for async log delivery.
• lib/multistream.js - Implements pino.multistream(); fans log records out to multiple destinations.
• lib/time.js - Provides epochTime and nullTime timestamp functions; stdTimeFunctions re-exports these.
• lib/worker.js - Worker-side bootstrap that imports and runs the user-specified transport target inside the worker thread.
• lib/caller.js - Detects the calling module for diagnostic purposes.
• lib/constants.js - DEFAULT_LEVELS map and SORTING_ORDER enum.
• lib/meta.js - Exports the current package version string.
• lib/deprecations.js - Emits process-warning deprecation notices for removed options.
• lib/transport-stream.js - Low-level stream bridge between Pino's write path and the transport worker.
• examples/basic.js - Minimal hello-world usage.
• examples/transport.js - Demonstrates pino.transport() with a file target.

Common pitfalls and fixes

• ESM/CJS interop: Pino is CJS-only; in an ESM project use import pino from 'pino' (Node resolves the default export automatically) and avoid named import { pino }.
• Worker transport not flushing on exit: The transport worker may not drain before the process exits; call logger.flush() in a process.on('exit', ...) handler or use pino.destination({ sync: false }) with sonic-boom's flushSync.
• level set below 'info' is silently ignored in production builds: Always pass level explicitly; do not rely on the LOG_LEVEL env var being picked up unless you wire it yourself in options.
• Child logger bindings are serialized at child-creation time: Mutating the object passed to .child() after creation has no effect; pass a new object for each request.
• Redact paths use dot notation and wildcards (*): Bracket notation (user['password']) is not supported; use user.password instead.
• Browser bundle size: pino.js pulls in Node builtins; point your bundler to browser.js via the browser field in package.json or an alias, otherwise bundle size balloons.

Vibe-coding prompt template

I have the Pino logger source at `vendor/pino/` and its integration guide at `USAGE.md`.
The upstream package is `user@example.com`.

Please integrate Pino into my project by doing the following steps:

1. Read `USAGE.md` and `vendor/pino/pino.d.ts` to understand the real API.
2. Create a `src/logger.ts` module that exports a root pino logger instance
   configured with:
   - level from process.env.LOG_LEVEL defaulting to 'info'
   - isoTime timestamps
   - redaction of ['req.headers.authorization', 'user.password']
   - base fields: { service: '<my-service-name>' }
3. In my Express app (`src/app.ts`), add middleware that creates a child logger
   per request with a unique requestId and attaches it to `req.log`.
4. Replace all existing `console.log` / `console.error` calls in `src/` with
   the appropriate `req.log` or root logger calls.
5. Add a pino.transport() call writing to `logs/app.log` in non-development
   environments.
6. Show me only the changed files with full content. Do not invent any Pino
   API that is not present in `vendor/pino/pino.d.ts` or `USAGE.md`.

License and credit

Pino is released under the MIT License (see source/LICENSE). Upstream repository: https://github.com/pinojs/pino. npm package: pino.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

JSON Object Signing and Encryption for Node.js

Automation, Utilities & Developer Tools

Free