mcpField
P
pino-logging

pino-logging

github.com/oakoss开发20196 次安装10 周前更新
代码仓库

关于 pino-logging

面向 Node.js 开发者的 Pino 使用指南，涵盖结构化 JSON 日志、请求级上下文、敏感数据脱敏和传输配置。

主要功能

  1. 01结构化 NDJSON 日志
  2. 02请求级子 Logger
  3. 03敏感字段脱敏
  4. 04工作线程传输
  5. 05HTTP 与框架日志

适用场景

  1. 01为 Node.js 服务添加结构化日志
  2. 02在请求日志中关联请求 ID
  3. 03脱敏密码或令牌
  4. 04将日志路由到多个目标

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill pino-logging

安装后在 Claude Code 中输入/pino-logging确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
child-loggers-and-redaction.md
http-and-frameworks.md
setup-and-configuration.md
transports.md

详细介绍

Pino 日志

适用于 Node.js 的高性能 JSON 日志记录器。传输在工作线程中运行，让主事件循环保持空闲。默认生成 NDJSON，并自动包含 level、time、pid、hostname 和 msg 字段。

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

不适用场景： 仅限浏览器的日志记录（pino 对浏览器的支持有限）、开发期间简单的 console.log 调试、默认需要人类可读日志的项目（pino 输出 JSON；开发时可使用 pino-pretty）。

Package： pino（v10+）

快速参考

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

常见错误

错误修复方法
在生产环境中使用 pino-pretty在生产环境中使用 JSON 输出；仅在开发环境中通过 transport 美化输出
记录敏感数据（令牌、密码）使用 redact 选项指定敏感字段的路径
每个请求都创建新的日志记录器使用 logger.child({ requestId }) 设置请求范围的上下文
通过文件写入阻塞主线程使用 pino.transport() —— 它会在工作线程中运行
对错误使用 JSON.stringify将错误作为 { err } 传递——pino 会序列化堆栈和原因链
未转发 X-Request-Id 标头在 pino-http 中使用 genReqId 优先检查标头
在热点循环中记录日志在执行开销较大的操作前检查 logger.isLevelEnabled('debug')
使用传输器时缺少 fetch-depth: 0传输器是独立的软件包——请将其安装为依赖项

委派

如果有 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

参考资料

评论

支持 Markdown