跳到主要内容
跳到主要内容

Next.js

ClickStack 可以从 Next.js 13.2 及以上版本的 Next.js serverless functions 中摄取原生 OpenTelemetry 跟踪（traces）。

本指南将集成：

  • 控制台日志（Console Logs）
  • 跟踪（Traces）
注意

如果你在寻找会话回放或浏览器端监控，请改为安装 Browser integration。

安装​

启用 instrumentation hook（v15 及以下版本必需）​

首先，您需要在 next.config.js 中将 experimental.instrumentationHook 设置为 true，以启用 Next.js instrumentation hook。

示例：

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
  // 忽略 OTel 包的警告 
  // https://github.com/open-telemetry/opentelemetry-js/issues/4173#issuecomment-1822938936
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack },
  ) => {
    if (isServer) {
      config.ignoreWarnings = [{ module: /opentelemetry/ }];
    }
    return config;
  },
};

module.exports = nextConfig;

安装 ClickHouse OpenTelemetry SDK​

npm install @hyperdx/node-opentelemetry

创建 Instrumentation 文件​

在 Next.js 项目的根目录下创建一个名为 instrumentation.ts（或 .js）的文件，并写入以下内容：

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@hyperdx/node-opentelemetry');
    init({
      apiKey: '<YOUR_INGESTION_API_KEY>', // 可选:通过 `HYPERDX_API_KEY` 环境变量配置
      service: '<MY_SERVICE_NAME>', // 可选:通过 `OTEL_SERVICE_NAME` 环境变量配置
      additionalInstrumentations: [], // 可选,默认值:[]
    });
  }
}

这将使 Next.js 能在调用任何 Serverless 函数时导入 OpenTelemetry 插桩。

配置环境变量​

如果你要将 trace 数据直接发送到 ClickStack，则需要在启动 Next.js 服务器时设置以下环境变量，以便将 span 转发到 OTel collector：

HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY> \
OTEL_SERVICE_NAME=<MY_SERVICE_NAME> \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
npm run dev

如果你在 Vercel 上进行部署，请确保为此次部署正确配置以上所有环境变量。