使用 @highlight-run/pino 将 pino 日志接入 highlight.io：Transport 配置与实现原理

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载导读pino 是 Node.js 生态中主打低开销、高速序列化的日志库其核心设计之一就是通过transport机制把日志流交给独立插件处理。本指南介绍开源全栈可观测平台 highlight.io 提供的官方 pino transport ——highlight-run/pino从一行配置接入、底层实现原理到可选参数调优帮助你以最小侵入的方式把 Node.js 服务的 pino 日志实时上报到 highlight.io并与会话回放、分布式追踪关联起来。快速接入在 pino 中挂载 highlight-run/pino transporthighlight-run/pino以 pino transport 的形式工作。你只需要在创建 pino logger 时把highlight-run/pino声明为 transport target并传入 highlight 项目 ID 即可。官方 READMEsdk/pino/README.md给出了完整的示例import pino from pino const logger pino({ level: info, transport: { targets: [ { target: highlight-run/pino, options: { projectID: YOUR_PROJECT_ID, }, level: info, }, ], }, }) logger.info(generating sitemap)关键点说明target: highlight-run/pino指向 transport 插件包包内默认导出的工厂函数会被 pino 在独立 worker 线程中调用options.projectID是必填项对应你在 highlight.io 创建的项目 ID用于把日志关联到正确的项目level决定该 target 接收的日志级别下限示例中设为info意味着debug/trace日志不会被转发targets数组意味着你可以把同一份日志同时发送到多个目的地例如终端输出 highlight.io原生的pino-pretty、文件输出等 transport 都可以与之共存。安装与包信息highlight-run/pino的包元数据定义在 sdk/pino/package.json当前版本0.1.6唯一运行时依赖highlight-run/nodeNode.js SDK二者在仓库内通过workspace: *关联发布时按版本解析构建工具tsup产物输出到distmain指向dist/index.js类型声明为dist/index.d.ts协议Apache-2.0。安装后只要你的项目里已有pino再补上 transport 包即可。由于 transport 的 worker 线程会在运行时动态加载请确保highlight-run/pino存在于node_modules中。深入实现transport 内部是如何工作的源码位于 sdk/pino/src/index.ts实现非常克制整体可拆解为四个阶段1. 非 Node 运行时短路pino常被用在 Next.js 等框架中而 Edge/Serverless 运行时并不具备 Node 的完整能力。transport 工厂函数首先检查process.env.NEXT_RUNTIMEif ( typeof process.env.NEXT_RUNTIME ! undefined process.env.NEXT_RUNTIME ! nodejs ) { return build(async () {}) }一旦检测到NEXT_RUNTIME已定义且不是nodejs就返回一个空实现保证 Edge 等环境不会因加载 Node SDK 而崩溃对应 CHANGELOG 0.1.6 的修复项 “ensure pino transport works correctly in non-node environments”。2. 惰性初始化 Highlight Node SDKtransport 工厂通过动态import(highlight-run/node)加载 SDK避免在纯日志场景下引入不必要的启动开销并复用全局单例const { H } await import(highlight-run/node) if (!H.isInitialized()) { H.init(options) } if (!options.projectID) { throw new Error(Highlight projectID not set) }其中H.init与H.isInitialized由 sdk/highlight-node/src/sdk.ts 提供init会以单例方式创建Highlight实例重复调用只初始化一次isInitialized返回实例是否已创建。若options.projectID缺失transport 会直接抛出异常提示你在 options 中补齐项目 ID。3. 逐条消费日志并映射级别transport 基于pino-abstract-transport的build()构造异步可迭代流逐条处理 pino 输出的 JSON 行。pino 内部用数字表示日志级别源码通过 switch 映射为 highlight 的字符串级别pino 数字级别含义映射字符串10tracetrace20debugdebug30infoinfo40warnwarn50errorerror60fatalfatal其他—兜底为info映射完成后调用H.log(msg, levelStr, secureSessionId, requestId, rest)把日志上报sdk/pino/src/index.ts。这里的rest是解构掉msg与level后剩余的字段即你通过第二个参数传入的结构化上下文logger.info({ userId, orderId }, message)中的userId、orderId等都会作为日志属性上报。每条日志的H.log调用都被 try/catch 包裹上报失败只会在控制台打印错误绝不阻塞业务日志输出。4. 关闭时冲刷缓冲transport 的close钩子会在 worker 结束前调用H.flush()确保积压的日志在进程退出前完整发送避免尾部日志丢失sdk/pino/src/index.ts。这与 Node SDK 中flush: () Promisevoid接口一一对应见 sdk/highlight-node/src/sdk.ts。配置选项NodeOptions 详解transport 的options就是highlight-run/node的NodeOptions类型定义在 sdk/highlight-node/src/types.ts。除 README 示例中的projectID外常用选项如下选项类型说明projectIDstring必填highlight 项目 ID用于将负载关联到项目otlpEndpointstringOTLP HTTP 上报端点默认https://otel.highlight.io:4318自托管部署时改为自己的 collector 地址serviceNamestring应用服务名用于在 highlight 中区分服务serviceVersionstring应用版本建议设置为最新部署的 git SHAenvironmentstring运行环境如development、staging、production用于区分本地与线上数据enableFsInstrumentationboolean是否启用 Nodefs自动埋点默认falseattributesAttributes追加到 OpenTelemetry Resource 的自定义属性serializeConsoleAttributesboolean是否尝试把 console 对象参数序列化进消息体上报端点的默认值在 sdk/highlight-node/src/client.ts 中定义为const OTLP_HTTP https://otel.highlight.io:4318。生产实践中建议至少设置serviceName与environment便于在 highlight.io 的日志检索与过滤中快速定位来源。会话与请求上下文关联pino transport 在消费日志时通过H.parseHeaders({})获取当前上下文sdk/pino/src/index.ts返回HighlightContextexport interface HighlightContext { secureSessionId: string | undefined requestId: string | undefined }定义见 sdk/highlight-node/src/types.ts。secureSessionId与requestId被传入每次H.log调用使日志能够与前端会话回放、后端 trace 建立关联。也就是说你在 highlight.io 查看某次会话或某条请求时可以顺藤摸瓜看到同一上下文下产生的 pino 日志。若要实现更精确的请求级关联应在 HTTP 处理链路中结合H.runWithHeaders/H.parseHeaders(请求头)使用见 sdk/highlight-node/src/sdk.tstransport 内部则以空头解析兜底。Next.js 与 Serverless 环境适配pino 常与 Next.js 搭配。如前所述transport 对NEXT_RUNTIME做了分支处理在 Node.js 运行时NEXT_RUNTIME nodejs或未定义正常初始化 SDK 并转发日志在 Edge 等非 Node 运行时返回空 transport静默降级保证应用不因缺少 Node API 而报错。这意味着你可以在 Next.js 项目里放心使用同一份 logger 配置Node 端获得完整上报能力Edge 端则安全跳过。这一行为在 sdk/pino/CHANGELOG.md 的 0.1.6 版本中有明确记录。常见问题与排查Highlight projectID not set报错options.projectID缺失。在 transport 配置中补上项目 ID并确认它来自 highlight.io 后台的项目设置。日志没有出现在 highlight.io先确认level阈值是否过低如误设为error导致info日志被过滤再检查otlpEndpoint是否指向了自托管 collector以及项目 ID 与上报环境是否匹配。进程退出丢日志transport 在close时调用H.flush()冲刷缓冲请确保应用退出流程走完了 pino 的 transport 关闭逻辑若日志量极大可适当调整 Node SDK 的批量处理器配置。上报失败不影响业务源码中每条日志的发送都包裹在 try/catch 中失败仅打印Failed to ingest logs to highlight: ...不会让日志调用抛出异常中断业务代码。版本演进速览从 sdk/pino/CHANGELOG.md 可以看到该包的演进脉络0.1.0首发版本0.1.3确保 console 序列化兼容BigInteger等不可序列化类型0.1.4调优 OpenTelemetry SDK 设置以降低内存占用并启用导出数据的 GZIP 压缩0.1.5修复 pino 日志级别上报不准确的问题同时升级了highlight-run/node3.6.60.1.6确保 transport 在非 Node 环境下正常工作依赖highlight-run/node3.7.1。总体而言highlight-run/pino是一个薄封装 transport配置面极小、失败不阻塞业务同时借助highlight-run/node的 OTLP 管道与批处理机制把 pino 日志无缝汇入 highlight.io 的全栈可观测视图。若需进一步阅读源码推荐从 sdk/pino/src/index.ts 与 sdk/highlight-node/src/client.ts 入手。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐mi-gpt Roadmap 深度解析从消息轮询到 RAG 与 MIoT Agent 的演进蓝图mi gpt Roadmap 深度解析从消息轮询到 RAG 与 MIoT Agent 的演进蓝图 本文以 docs/roadmap.md https://li可观测性后端Pino Pretty Printing 完全指南用 pino-pretty 将 NDJSON 日志渲染为开发环境友好输出Pino Pretty Printing 完全指南用 pino pretty 将 NDJSON 日志渲染为开发环境友好输出 Pino 默认产出以换行符分隔的Pino-Pretty 日志美化工具使用指南Pino Pretty 日志美化工具使用指南 Pino Pretty 是一个专为 Pino 日志库设计的日志美化工具它能够将结构化的 JSON 日志转换为更易开发工具上一篇Tars熔断恢复成功率提升策略优化恢复逻辑与参数配置下一篇QZXing 解码失败排查9 个常见问题与解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考