pino-logging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pino Logging

Pino 日志

High-performance JSON logger for Node.js. Transports run in worker threads to keep the main event loop free. Produces NDJSON by default with automatic

level

time

pid

hostname

, and

msg

fields.

When to use: Structured logging in Node.js applications, request-scoped logging with correlation IDs, sensitive data redaction, multi-destination log routing, framework logging integration.

When NOT to use: Browser-only logging (pino has limited browser support), simple

console.log

debugging during development, projects that need human-readable logs by default (pino outputs JSON; use

pino-pretty

for dev).

Package:

pino

(v10+)

适用于 Node.js 的高性能 JSON 日志工具。传输进程运行在 worker 线程中，避免阻塞主事件循环。默认生成 NDJSON 格式日志，自动包含

level

、

time

、

pid

、

hostname

和

msg

字段。

适用场景： Node.js 应用中的结构化日志、带关联 ID 的请求域日志、敏感数据脱敏、多目标日志路由、框架日志集成。

不适用场景： 仅浏览器端的日志记录（Pino 对浏览器支持有限）、开发阶段简单的

console.log

调试、默认需要人类可读格式日志的项目（Pino 输出 JSON 格式；开发环境可使用

pino-pretty

美化输出）。

包：

pino

（v10+）

Quick Reference

速查参考

Pattern	API	Key Points
Basic logger	`pino()`	Defaults: level `info` , JSON to stdout
Set level	`pino({ level: 'debug' })`	`fatal > error > warn > info > debug > trace`
Log with context	`logger.info({ userId }, 'msg')`	First arg is merged object, second is message
Error logging	`logger.error({ err }, 'failed')`	Pass errors as `err` key for serialization
Child logger	`logger.child({ requestId })`	Bindings persist on all child logs
Redaction	`pino({ redact: ['password'] })`	Paths use dot notation, supports wildcards
Transport (worker)	`pino({ transport: { target } })`	Runs in worker thread, non-blocking
Multiple transports	`transport: { targets: [...] }`	Different levels per destination
Pretty print (dev)	`target: 'pino-pretty'`	Dev only — not for production
File transport	`target: 'pino/file'`	Built-in, with `mkdir` option
Rotating files	`target: 'pino-roll'`	Size and time-based rotation
HTTP middleware	`pinoHttp()` from `pino-http`	Auto request/response logging
Request ID	`genReqId` option in pino-http	Generate or forward `X-Request-Id`
Serializers	`serializers: { req, res, err }`	Transform objects before logging
Formatters	`formatters: { level, log }`	Rename fields, transform output
Custom levels	`customLevels: { http: 35 }`	Add levels between built-in ones
Async destination	`pino.destination({ sync: false })`	Buffered async writes
Fastify	`fastify({ logger: true })`	Built-in pino, `request.log`
Hono	`hono-pino` middleware	`c.get('logger')` in handlers

模式	API 接口	核心要点
基础日志实例	`pino()`	默认配置：日志级别 `info` ，JSON 输出至标准输出
设置日志级别	`pino({ level: 'debug' })`	级别优先级： `fatal > error > warn > info > debug > trace`
带上下文日志	`logger.info({ userId }, 'msg')`	第一个参数为待合并的上下文对象，第二个为日志消息
错误日志记录	`logger.error({ err }, 'failed')`	将错误以 `err` 键传入，Pino 会自动序列化错误信息
子日志实例	`logger.child({ requestId })`	绑定的上下文会保留在所有子日志的输出中
数据脱敏	`pino({ redact: ['password'] })`	路径支持点表示法，可使用通配符
线程化传输	`pino({ transport: { target } })`	在 worker 线程中运行，不会阻塞主线程
多目标传输	`transport: { targets: [...] }`	可为不同目标设置不同的日志级别
开发环境美化	`target: 'pino-pretty'`	仅用于开发环境——请勿在生产环境使用
文件传输	`target: 'pino/file'`	内置功能，支持 `mkdir` 选项
日志轮转	`target: 'pino-roll'`	支持按大小和时间轮转日志文件
HTTP 中间件	`pinoHttp()` （来自 `pino-http` ）	自动记录请求/响应日志
请求 ID 配置	pino-http 中的 `genReqId` 选项	生成或转发 `X-Request-Id` 头部信息
序列化器	`serializers: { req, res, err }`	日志输出前转换对象格式
格式化器	`formatters: { level, log }`	重命名字段、转换输出格式
自定义级别	`customLevels: { http: 35 }`	可在内置级别之间添加自定义日志级别
异步写入目标	`pino.destination({ sync: false })`	基于缓冲的异步写入
Fastify 集成	`fastify({ logger: true })`	内置 Pino 支持，可通过 `request.log` 访问日志实例
Hono 集成	`hono-pino` 中间件	处理器中可通过 `c.get('logger')` 获取日志实例

Common Mistakes

常见错误

Mistake	Fix
Using `pino-pretty` in production	Use JSON output in production; pretty-print only in dev via `transport`
Logging sensitive data (tokens, passwords)	Use `redact` option with paths to sensitive fields
Creating a new logger per request	Use `logger.child({ requestId })` for request-scoped context
Blocking main thread with file writes	Use `pino.transport()` — runs in a worker thread
Using `JSON.stringify` on errors	Pass errors as `{ err }` — pino serializes stack, cause chain
Not forwarding `X-Request-Id` header	Use `genReqId` in pino-http to check headers first
Logging inside hot loops	Check `logger.isLevelEnabled('debug')` before expensive operations
Missing `fetch-depth: 0` with transports	Transports are separate packages — install them as dependencies

错误操作	修复方案
在生产环境使用 `pino-pretty`	生产环境使用 JSON 格式输出；仅在开发环境通过 `transport` 配置美化输出
记录敏感数据（令牌、密码等）	使用 `redact` 选项指定敏感字段的路径
每个请求创建新的日志实例	使用 `logger.child({ requestId })` 创建请求域的上下文日志实例
文件写入阻塞主线程	使用 `pino.transport()` —— 运行在 worker 线程中，避免阻塞
对错误使用 `JSON.stringify` 序列化	将错误以 `{ err }` 形式传入 —— Pino 会自动序列化堆栈信息、错误链
未转发 `X-Request-Id` 头部信息	在 pino-http 中使用 `genReqId` 配置，优先从请求头部获取该 ID
在高频循环中记录日志	在执行昂贵操作前，先通过 `logger.isLevelEnabled('debug')` 检查日志级别是否开启
使用传输时缺少 `fetch-depth: 0` 配置	传输模块是独立包 —— 需要将其作为依赖安装

Delegation

任务委托

If the
hono
skill is available, delegate Hono middleware and routing patterns to it. If the
vitest-testing
skill is available, delegate test setup and mocking patterns to it. If the
sentry-setup-logging
skill is available, delegate Sentry integration to it — it covers
Sentry.pinoIntegration()
for forwarding pino logs to Sentry. Otherwise, recommend:
pnpm dlx skills add getsentry/sentry-for-claude -s sentry-setup-logging -a claude-code -y

若
hono
技能可用，将 Hono 中间件和路由相关的模式委托给该技能处理。若
vitest-testing
技能可用，将测试设置和模拟相关的模式委托给该技能处理。若
sentry-setup-logging
技能可用，将 Sentry 集成相关内容委托给该技能处理 —— 它涵盖了
Sentry.pinoIntegration()
用于将 Pino 日志转发至 Sentry 的配置。否则，推荐执行：
pnpm dlx skills add getsentry/sentry-for-claude -s sentry-setup-logging -a claude-code -y

References

参考资料

Setup, configuration, and core API
Transports, destinations, and log routing
Child loggers, serializers, and redaction
HTTP logging, correlation IDs, and framework integrations

安装、配置与核心 API
传输、目标与日志路由
子日志实例、序列化器与数据脱敏
HTTP 日志、关联 ID 与框架集成