OpenTelemetry JS 在 Next.js 项目中实现 HTTP 路由监控的最佳实践

背景介绍

在现代 Web 应用开发中，Next.js 作为一种流行的 React 框架，因其服务端渲染能力而广受欢迎。而 OpenTelemetry 作为云原生时代可观测性的标准解决方案，能够帮助开发者监控应用性能。本文将探讨如何在 Next.js 项目中正确配置 OpenTelemetry JS 来实现 HTTP 路由级别的监控。

问题现象

开发者在 Next.js 项目中配置 OpenTelemetry 的 HTTP 监控时，发现生成的指标数据中缺少关键的 http.route 属性。这导致无法区分不同路由的性能表现，降低了监控数据的实用价值。

技术原理分析

OpenTelemetry 的 HTTP 监控基于 Node.js 的 http 模块实现。然而，http 模块本身并不具备"路由"的概念，路由是更高层次的框架（如 Express、Next.js）引入的抽象概念。因此，默认情况下，HttpInstrumentation 不会自动捕获路由信息。

解决方案

1. 配置上下文管理器

首先需要确保正确配置了上下文管理器。OpenTelemetry 默认使用无操作上下文管理器，需要替换为 AsyncLocalStorageContextManager：

import { context } from "@opentelemetry/api";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";

context.setGlobalContextManager(new AsyncLocalStorageContextManager());

2. 使用 RPC 元数据设置路由

在 HttpInstrumentation 的 requestHook 中，可以通过 RPC 元数据机制手动设置路由信息：

new HttpInstrumentation({
  requestHook: (span, request) => {
    const route = (request as IncomingMessage)?.url;
    if (route) {
      const rpcMetadata = getRPCMetadata(context.active());
      if (rpcMetadata) {
        if (rpcMetadata?.type === RPCType.HTTP) {
          rpcMetadata.route = route;
        }
      } else {
        setRPCMetadata(context.active(), {
          type: RPCType.HTTP,
          route,
          span,
        });
      }
    }
  },
})

3. 完整配置示例

以下是 Next.js 项目中完整的 OpenTelemetry 配置示例：

// otel-prometheus.ts
import { context } from "@opentelemetry/api";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
import { getRPCMetadata, RPCType, setRPCMetadata } from "@opentelemetry/core";
import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
import { HostMetrics } from "@opentelemetry/host-metrics";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { RuntimeNodeInstrumentation } from "@opentelemetry/instrumentation-runtime-node";
import { Resource } from "@opentelemetry/resources";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { IncomingMessage } from "http";

context.setGlobalContextManager(new AsyncLocalStorageContextManager());

const exporter = new PrometheusExporter({ port: 9464 });
const meterProvider = new MeterProvider({ readers: [exporter] });

registerInstrumentations({
  meterProvider,
  instrumentations: [
    new HttpInstrumentation({
      requestHook: (span, request) => {
        const route = (request as IncomingMessage)?.url;
        if (route) {
          const rpcMetadata = getRPCMetadata(context.active());
          if (rpcMetadata) {
            if (rpcMetadata?.type === RPCType.HTTP) {
              rpcMetadata.route = route;
            }
          } else {
            setRPCMetadata(context.active(), {
              type: RPCType.HTTP,
              route,
              span,
            });
          }
        }
      },
    }),
    new RuntimeNodeInstrumentation(),
  ],
});

未来改进方向

OpenTelemetry 社区已经认识到这个问题，并计划在未来版本中提供专门的指标钩子功能，使路由监控更加简单直观。这将进一步简化在 Next.js 等框架中的监控配置。

总结

通过本文介绍的方法，开发者可以在 Next.js 项目中实现完整的 HTTP 路由级别监控。关键在于正确配置上下文管理器，并利用 RPC 元数据机制传递路由信息。这种方案不仅适用于 Next.js，也可以应用于其他基于 Node.js http 模块的框架。

对于生产环境，建议持续关注 OpenTelemetry 的更新，未来版本可能会提供更优雅的解决方案。同时，开发者也可以考虑封装自己的监控工具函数，以简化配置过程并提高代码复用性。