Next.js 15 instrumentation.ts 全局观测与初始化实践 OTEL-日志-计量

概览`instrumentation.ts` 在 Next.js 15 中用于定义应用的全局初始化逻辑。适合设置 OpenTelemetry、日志与计量的基础配置，使 App Router 与 Edge 路由共享一致的观测上下文。文件结构// instrumentation.ts

export async function register() {

// 初始化观测配置，例如设置环境变量或全局对象

globalThis.__appStart = Date.now()

}

与 OTEL 协同// 可在 register 中配置全局导出端点与采样策略（示意）

export async function register() {

globalThis.__otel = { endpoint: process.env.OTLP_HTTP_EXPORT, sampleRate: 1 }

}

在路由中使用上下文// app/api/health/route.ts

export const runtime = 'edge'

export async function GET() {

const started = (globalThis as any).__appStart

return Response.json({ up: true, started })

}

治理要点将与运行期相关的初始化逻辑集中在 `instrumentation.ts`，减少分散配置。对 Edge 与 Node 路由保持一致的上下文对象或配置。与环境变量与密钥管理协作，避免在客户端泄露敏感信息。验证与指标Next.js：15.0+；Node.js：20.x；Edge Runtime：兼容全局初始化完成且路由可读上下文；观测配置一致