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 可实现一致的可观测性；建议建立指标/日志/追踪的统一配置与告警闭环。