@0xchain/telemetry

telemetry

面向 Next.js 16 App Router 的链路追踪方案，提供巡检识别、请求过滤与多维采样能力，基于 OpenTelemetry 输出。

快速开始

1. 安装依赖

pnpm add @0xchain/telemetry

Monorepo 内使用：在应用包的 package.json 中添加 "@0xchain/telemetry": "workspace:*"，然后执行 pnpm install。使用前需先构建 telemetry 包：pnpm nx run telemetry:build 或 cd packages/telemetry && pnpm exec vite build。

2. 初始化追踪 (instrumentation.ts)

在项目根目录（或 src 目录）创建 instrumentation.ts，只需一行代码即可启用：

注意：请从 @0xchain/telemetry/instrumentation 导入。此入口包含完整 Node SDK，仅在 instrumentation.ts 中加载，不影响 Edge 的 middleware bundle。

import { registerTelemetry } from "@0xchain/telemetry/instrumentation";

export async function register() {
  // 自动从环境变量加载配置
  await registerTelemetry();
}

或者自定义配置：

import { registerTelemetry } from "@0xchain/telemetry/instrumentation";

export async function register() {
  await registerTelemetry({
    serviceName: "my-web-app",
    environment: "production",
    // 更多配置...
  });
}

3. 注入中间件 (middleware.ts)

在 middleware.ts 中使用 withTelemetryMiddleware 包裹现有中间件，实现低侵入式集成：

注意：请从 @0xchain/telemetry/middleware 或 @0xchain/telemetry/next 导入。此入口轻量，无 Node SDK 依赖，适用于 Edge Runtime。

import { NextResponse } from "next/server";
import { withTelemetryMiddleware } from "@0xchain/telemetry/middleware";

// 你的现有中间件逻辑
const userMiddleware = async (req) => {
  // ... 业务逻辑
  return NextResponse.next();
};

// 使用 withTelemetryMiddleware 包裹
export const middleware = withTelemetryMiddleware(userMiddleware);

export const config = {
  matcher: [
    /* 你的 matcher 配置 */
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
};

如果你没有其他中间件，可以使用工厂方法：

import { createTelemetryMiddleware } from "@0xchain/telemetry/middleware";

export const middleware = createTelemetryMiddleware();

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

环境变量配置

支持通过环境变量实现零代码配置：

变量名	描述	默认值
OTEL_SERVICE_NAME	服务名称	unknown-service
OTEL_SERVICE_VERSION	服务版本	1.0.0
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 上报地址	-
OTEL_EXPORTER_OTLP_HEADERS	OTLP Headers (k=v,k2=v2)	-
TELEMETRY_ENVIRONMENT	环境名称 (dev/prod)	development，在 Vercel 上自动使用 VERCEL_ENV
TELEMETRY_SAMPLING_RATIO	默认采样率 (0.0-1.0)	0.01
TELEMETRY_IGNORE_PATHS	忽略路径 (逗号分隔)	默认忽略静态资源
TELEMETRY_INSPECTION_HEADER	巡检请求头	x-inspection
TELEMETRY_CONFIG_FILE	配置文件路径，支持 JSON，异步读取不阻塞启动	-

Vercel 集成

部署到 Vercel 时，将自动检测并注入以下 resource 属性：

• vercel.region、vercel.runtime、vercel.sha、vercel.host、vercel.deployment_id
• environment 优先使用 VERCEL_ENV（production / preview / development）

核心特性

• 巡检识别：自动识别 x-inspection 请求头，强制采样并全量记录。
• 智能过滤：内置静态资源过滤规则，支持自定义路径、扩展名和方法过滤。
• 多维采样：支持按路径、用户类型、状态码配置不同的采样率。
• 低侵入性：通过 HOC 方式集成中间件，不破坏原有逻辑。
• 入口拆分：instrumentation 含完整 Node SDK；middleware / next 轻量，仅注入请求头，适合 Edge。
• 按需加载：仅启用 HTTP + Undici 检测，减少冷启动与内存占用。

常见问题

Module not found: Can't resolve '@0xchain/telemetry/instrumentation'

• 确认依赖：确保应用 package.json 中有 @0xchain/telemetry 依赖。
• 确认构建：telemetry 包需先构建，dist/ 目录需存在。在 monorepo 根目录执行 pnpm nx run telemetry:build。
• Next.js 配置：若仍有问题，可在 next.config.js 中添加 transpilePackages: ['@0xchain/telemetry']。

高级配置

采样规则配置 (Sampling Rules)

可以通过 samplingRules 字段或 TELEMETRY_SAMPLING_RULES 环境变量（JSON 字符串）配置：

[
  {
    "name": "critical-api",
    "ratio": 1.0,
    "when": { "path": ["/api/checkout", "/api/payment"] }
  },
  {
    "name": "errors",
    "ratio": 1.0,
    "when": { "minStatusCode": 500 }
  },
  {
    "name": "guest-users",
    "ratio": 0.05,
    "when": { "userType": ["guest"] }
  }
]