Next.js OpenTelemetry 可观测性技能 (nextjs-otel)
一个模块化、生产就绪的工作流，用于在 Next.js App Router 应用中配置、测试和验证 OpenTelemetry 跟踪，标准化单一终止开关，防止 @vercel/otel 初始化错误，并自动执行跟踪验证。
工作流概览
flowchart TD
A["1. 项目评估<br/>(App Router & package.json)"] --> B["2. 安装依赖<br/>(@vercel/otel & @opentelemetry/api)"]
B --> C["3. 部署 instrumentation.ts<br/>(registerOTel + onRequestError)"]
C --> D["4. 配置环境<br/>(.env.example & .env.local)"]
D --> E["5. 验证与测试<br/>(模拟收集器与终止开关)"]
逐步执行操作手册
按以下顺序依次执行，以配置和验证 OpenTelemetry 可观测性：
1. 项目发现与依赖检查
- 检查项目结构：确认
package.json中的 Next.js App Router 版本和包管理器 (pnpm、bun、npm)。 - 定位检测根目录：检查项目是否使用根目录
instrumentation.ts或src/instrumentation.ts。 - 审查架构标准：查阅 architectural-standards.md，了解单一终止开关纪律和运行时边界。
2. 安装依赖
- 安装核心遥测包：
pnpm add @vercel/otel @opentelemetry/api
3. 部署 instrumentation.ts
- 创建检测文件：将 instrumentation.ts.template 部署到根目录或
src/目录。 - 应用真值保护：确保
register()在process.env.OTEL_SDK_DISABLED严格不等于"true"时删除该环境变量，以避免@vercel/otel的布尔值评估错误。 - 接入错误跟踪：确保
onRequestError()将next.error.digest、路由路径和 HTTP 元数据捕获到活动跨度中。
4. 配置环境变量
- 更新环境模板：使用 env.otel.template 将 OpenTelemetry 配置注入到
.env.example和.env.local。 - 设置服务名称与协议：配置
OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT和OTEL_EXPORTER_OTLP_PROTOCOL=http/json。
5. 验证与测试
- 启动模拟 OTLP 收集器：按照 verification-and-testing.md 在端口 4318 上启动测试收集器：
node .agents/skills/nextjs-otel/scripts/mock_collector.js - 验证活动跟踪 (
OTEL_SDK_DISABLED=false)：触发测试请求 (curl http://localhost:3000/) 并验证POST /v1/traces批次返回 HTTP 200 OK。 - 验证终止开关 (
OTEL_SDK_DISABLED=true)：确认 Next.js 服务器日志显示[OTel] Instrumentation hook skipped并导出 0 条跟踪。 - 输出验证报告：生成 Markdown 格式摘要报告。
边界情况与已知 AI 陷阱
[!WARNING]
@vercel/otel字符串真值错误：@vercel/otel使用!!process.env.OTEL_SDK_DISABLED进行评估。在 JavaScript 中，Boolean("false")结果为true。如果没有在process.env.OTEL_SDK_DISABLED不为'true'时删除该变量，设置OTEL_SDK_DISABLED=false将静默禁用跟踪。- 辅助自定义标志：切勿引入
OTEL_ENABLED与OTEL_SDK_DISABLED并存。严格统一使用OTEL_SDK_DISABLED。- 运行时边界违规：切勿将
instrumentation.ts或服务端 OpenTelemetry SDK 导入到客户端组件 ("use client") 中。- 链式命令：不要使用链式命令（
&&、||、;）。所有设置和测试命令需单独执行。
输出摘要模式
完成 OpenTelemetry 设置或验证后，输出结构化报告：
# OpenTelemetry 验证报告
## 状态摘要
- **OTel 状态**：启用 / 禁用
- **服务名称**：<已配置的服务名称>
- **目标端点**：<已配置的端点>
- **导出协议**：http/json | http/protobuf
## 验证结果
| 检查项 | 预期结果 | 实际结果 | 状态 |
| :------------------------- | :------------------------- | :----------------- | :--- |
| 初始化钩子 | 已注册 | 已注册 | 通过 |
| 跟踪分派（启用） | POST /v1/traces (200 OK) | 接收 X 批次 | 通过 |
| 终止开关（禁用） | 跳过，0 条跟踪 | 跳过，0 条跟踪 | 通过 |
| 类型检查 | 0 个错误 | 0 个错误 | 通过 |