Next.js 15 全栈可观测性：OpenTelemetry 链路追踪、Sentry 异常捕获与 Prometheus 指标中枢

在现代大型分布式全栈架构中，当一个线上用户反馈“点击结账按钮后页面卡住了”，或者“某个博客页面偶尔打开需要 8 秒”，在没有可观测性基础设施的裸奔系统中，排查往往沦为“在大海捞针式的 console.log 中盲猜”的噩梦：到底是因为前端发起了瀑布式请求？还是 Edge 中间件鉴权超时？亦或是服务端直连数据库时遭遇了连接池死锁？

现代企业级软件工程将可观测性（Observability） 拆解为三大核心支柱：Metrics（度量指标）、Logs（结构化日志）、Traces（全链路分布式追踪）。Next.js 15 依托官方首创的 instrumentation.ts 运行时生命周期钩子，以及与业界标准 OpenTelemetry（简称 OTel） 的深度原生集成，使得全栈架构师能够在毫秒级精度上监控每一个 HTTP 请求在浏览器、边缘中间件、服务端渲染组件与远程数据库之间的每一个耗时跨度（Span）。本文将系统拆解这套工业级可观测性全景实战。

1. 现代全栈可观测性三大支柱拓扑

+-------------------------------------------------------------------------+
|                  Next.js 15 全栈立体可观测性架构全景                     |
+-------------------------------------------------------------------------+

[用户浏览器客户端]
- 捕获 Core Web Vitals (LCP, INP, CLS)
- Sentry 捕获未处理 JS 运行时异常与用户操作回放 (Session Replay)
                        |
                        | (带着 HTTP Header: traceparent: 00-4bf92f3577b34da6...)
                        v
[Next.js 15 Edge / Node 服务端 (instrumentation.ts)]
- 启动 OpenTelemetry Node SDK
- 自动为每一个 Route Handler, Server Action, Server Component 注入 Span
                        |
       +----------------+----------------+
       |                                 |
       v                                 v
[OTel Collector 收集器]             [Prometheus 指标端点 (/api/metrics)]
- Jaeger / Grafana Tempo (分布式链路追踪)   - 系统 CPU / 内存 / QPS / 响应延迟直方图
- Grafana Loki (结构化 JSON 日志)          - Grafana 实时监控大屏

1.1 分布式链路追踪（Distributed Tracing）与 Trace Context

Trace：代表一次请求从发起到完全结束的完整生命周期（例如用户访问一次文章详情页）。
Span：代表 Trace 内部某一个具体的工作单元（例如：“解析 JWT 耗时 2ms”、“Drizzle 查库耗时 24ms”、“Flight Payload 序列化耗时 8ms”）。
W3C Trace Context 规范：Next.js 与前后端系统通过标准的 traceparent 请求头在网络边界传递分布式 TraceId，保证即便请求穿透了多个独立微服务，所有日志依然能在统一的追踪图谱中精准对齐！

2. Next.js 15 原生 instrumentation.ts 深度实战

instrumentation.ts 是 Next.js 15 专门用于监控和遥测初始化的约定式核心文件。它在服务启动的最早阶段执行，且支持针对 Node.js 和 Edge 运行时的差异化引导：

// src/instrumentation.ts
export async function register() {
  // 仅在 Node.js 服务端环境下初始化 OpenTelemetry SDK
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { NodeSDK } = await import('@opentelemetry/sdk-node');
    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
    const { Resource } = await import('@opentelemetry/resources');
    const { SemanticResourceAttributes } = await import('@opentelemetry/semantic-conventions');
    const { getNodeAutoInstrumentations } = await import('@opentelemetry/auto-instrumentations-node');

    // 1. 初始化标准 OTLP 导出器 (发送至 Grafana Tempo / Jaeger)
    const traceExporter = new OTLPTraceExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
    });

    // 2. 组装 OTel 核心 SDK
    const sdk = new NodeSDK({
      resource: new Resource({
        [SemanticResourceAttributes.SERVICE_NAME]: 'monsterai-tech-blog',
        [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
        [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV,
      }),
      traceExporter,
      // 自动拦截 http, fs, pg, dns 等原生库的调用
      instrumentations: [getNodeAutoInstrumentations()],
    });

    // 3. 启动遥测追踪
    sdk.start();
  }
}

2.1 开启 Next.js 内部性能埋点

在 next.config.mjs 中显式启用实验性可观测性埋点：

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true, // 激活 instrumentation.ts
  },
};

export default nextConfig;

开启后，Next.js 内部会自动发射诸如 NextNodeServer.handleRequest、AppRouteRouteHandlers.run 等底层精密 Span，无需开发者手写任何侵入式打点代码！

3. 手动埋点：业务级 Custom Spans 与错误标记

在执行如复杂加密、大图转码或重要算法仿真时，我们可以通过 OpenTelemetry API 创建细粒度的业务自定义 Span：

// src/lib/telemetry.ts
import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('monsterai-core-tracer');

export async function traceAsyncOperation<T>(
  spanName: string,
  fn: () => Promise<T>,
  attributes?: Record<string, string | number>
): Promise<T> {
  return tracer.startActiveSpan(spanName, async (span) => {
    if (attributes) {
      span.setAttributes(attributes);
    }
    try {
      const result = await fn();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (err: any) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: err.message || '未知业务异常',
      });
      span.recordException(err);
      throw err;
    } finally {
      span.end(); // 必须显式结束 Span
    }
  });
}

4. 客户端 Core Web Vitals 自动化闭环上报

在用户端，为了量化真实世界中全球用户的访问性能（Real User Monitoring, RUM），我们可以使用 Next.js 提供的 useReportWebVitals Hook：

// src/app/vitals.tsx
'use client';

import { useReportWebVitals } from 'next/navigation';

export function WebVitalsReporter() {
  useReportWebVitals((metric) => {
    // 过滤出核心性能指标: LCP, INP, CLS, TTFB, FID, FCP
    const payload = {
      name: metric.name,
      value: metric.value,
      rating: metric.rating, // 'good' | 'needs-improvement' | 'poor'
      delta: metric.delta,
      id: metric.id,
      pathname: window.location.pathname,
      navigationType: (metric as any).navigationType,
    };

    // 使用 sendBeacon 保证在用户关闭标签页时依然能可靠送达
    const blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
    if (navigator.sendBeacon) {
      navigator.sendBeacon('/api/telemetry/vitals', blob);
    } else {
      fetch('/api/telemetry/vitals', {
        body: blob,
        method: 'POST',
        keepalive: true,
      });
    }
  });

  return null;
}

5. 生产级告警与 SLO / SLA 容灾自检表

可观测性的终极目的是驱动自动化故障自愈与精准告警。团队应建立以下生产指标大盘：

[✓] 1. P99 延迟 SLO 设立: 核心 Route Handlers 与文章详情页 P99 首字节响应时间 (TTFB) 必须 < 250ms。
[✓] 2. 5xx 错误率熔断报警: 全站 5xx 错误响应占比超过 0.5% 时，立即触发 PagerDuty / 飞书电话告警。
[✓] 3. 敏感凭据脱敏: 严禁将用户明文密码、银行卡号、Authorization 密钥记录进 OTel Span 或日志中。
[✓] 4. 采样率动态调优: 在高并发海量请求下，将 Trace 采样率调整为 5%~10%，防止遥测数据撑爆存储。
[✓] 5. Sentry SourceMap 对齐: 在 CI/CD 构建流水线中自动上传 SourceMap，并在部署后立刻从公开目录清理。

通过 OpenTelemetry 链路追踪的纵深洞察、Core Web Vitals 的真实用户端体验反馈与生产级指标大盘的闭环联动，我们彻底驱散了线上黑盒运维的迷雾，为 Next.js 15 企业级系统铸就了固若金汤的坚韧根基。

6. Sentry 异常捕获与 Session Replay 录屏级定位

在全栈监控中，单纯知道“线上抛出了一个 TypeError”往往无济于事，因为开发者很难复现导致该错误的复杂用户操作时序。Sentry Session Replay 提供了在严格遵循用户隐私合规前提下的像素级 DOM 录屏回放能力。

+-------------------------------------------------------------------------+
|               Sentry 异常与会话回放 (Session Replay) 联动                |
+-------------------------------------------------------------------------+

[用户在生产环境发生未捕获异常: TypeError: Cannot read property of undefined]
                                   |
                                   v
[Sentry Client SDK 自动拦截]
- 捕获完整调用栈 (Stack Trace)
- 提取发生错误前 10 次点击、滚动、URL 路由切换面包屑 (Breadcrumbs)
- 提取前 30 秒的加密 DOM 变动回放录屏 (自动脱敏所有密码、姓名、卡号文本)
                                   |
                                   v
[向 Sentry 平台发送事件载荷: Error + ReplayId + TraceId]
                                   |
[工程师在 Sentry 后台像看视频一样 1:1 重看用户操作，30 秒定位 Bug 根因!]

6.1 Next.js 15 生产级 Sentry 配置

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  // 采样率策略: 生产环境 Trace 采样 10%，错误会话 100% 录屏
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.05,
  replaysOnErrorSampleRate: 1.0, // 只要出错立即开启录屏回放
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true, // 严格遮罩所有文本，保障隐私安全
      blockAllMedia: true,
    }),
  ],
});

7. Prometheus + Grafana 指标端点与全量看板构建

对于私有云部署或 VPS 自建服务器，除了外部 SaaS 监控外，基于 Prometheus + Grafana 的自建指标体系是运维中枢的标准配置。

// src/app/api/metrics/route.ts
import { NextResponse } from 'next/server';
import client from 'prom-client';

// 收集 Node.js 运行时默认指标 (内存、GC 停顿、事件循环延迟)
const collectDefaultMetrics = client.collectDefaultMetrics;
collectDefaultMetrics({ prefix: 'monsterai_' });

// 自定义业务指标: 文章浏览量计数器
export const articleViewsCounter = new client.Counter({
  name: 'monsterai_article_views_total',
  help: '全站文章阅读总量计数',
  labelNames: ['slug', 'category'],
});

export async function GET() {
  const metrics = await client.register.metrics();
  return new NextResponse(metrics, {
    headers: {
      'Content-Type': client.register.contentType,
      'Cache-Control': 'no-store',
    },
  });
}

通过在 Prometheus 中定期 scrape /api/metrics 端点，结合 Grafana 监控大屏，全栈团队能够实时掌握每秒请求量（QPS）、V8 堆内存使用趋势以及慢接口耗时分布，让系统的每一个脉搏都清晰透明。