Next.js instrumentation.ts 与 OpenTelemetry 集成实践

---

标题: Next.js instrumentation.ts 与 OpenTelemetry 集成实践

关键词:

• instrumentation.ts
• OpenTelemetry
• Tracing
• Logs
• Observability

描述: 说明在 Next.js 项目中使用 instrumentation.ts 接入 OpenTelemetry 的流程与注意事项，结合缓存与构建架构进行端到端观测，附官方文档验证。

categories:

• 文章资讯
• 技术教程

---

引言

• Next.js 提供 instrumentation.ts 钩子在应用启动阶段注入观测逻辑；配合 OpenTelemetry 可实现跨页面/服务的链路追踪与日志统一。

集成步骤（已验证）

• 创建 instrumentation.ts：在 src 或根目录加入文件以注册初始化逻辑（如 OTEL provider、exporter 设置）。来源：Next.js 文档 instrumentation。
• 采集内容：记录路由导航、Server Actions、Route Handlers 等关键阶段的 span 与属性；统一错误上报。来源：同文档与社区实践。
• 与缓存/构建协作：在使用 Cache Components/PPR/Turbopack 时标注缓存命中与构建分块信息，便于关联性能指标。来源：Next.js 15/16 官方博客。

注意事项

• 环境隔离：在 development/staging/production 分别使用不同采样率与导出端点。
• 安全与隐私：避免在 span 属性中写入 PII；在日志中做脱敏与聚合。

参考链接（验证来源）

• Next.js 文档：Instrumentation Hook（英文）：https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
• Next.js 官方博客：15/16（缓存与构建增强）：https://nextjs.org/blog/next-15 与 https://nextjs.org/blog/next-16
• OpenTelemetry 官方：概览与 SDK：https://opentelemetry.io/

结语

• 借助 instrumentation.ts 与 OpenTelemetry，Next.js 可实现一致的可观测性；建议建立指标/日志/追踪的统一配置与告警闭环。