使用托管 ClickStack 为应用程序埋点

介绍如何使用 OpenTelemetry 为 Node.js 应用程序埋点，并将日志、指标和链路追踪发送到托管 ClickStack

本指南介绍如何使用 OpenTelemetry 为一个简单的 Node.js 应用埋点，并将其日志、指标和链路追踪发送到托管 ClickStack。后端的埋点无需更改应用源代码。

HackerNews Analyzer 是一个小型 Node.js 应用，用于查询托管在公网 ClickHouse 演示实例中的 HackerNews 数据集。每个图表、表格和搜索框背后都对应一个真实的 ClickHouse 查询，因此每次交互都会生成一条 trace，其中主 span 是后端发往 ClickHouse 的 HTTPS 调用。

前置条件

• 一个可用且可访问的 OTel collector，并已配置为将数据摄取到你的托管 ClickStack 服务中。你需要其 OTLP 端点和摄取令牌。
• Node 18+ 和 npm。

1. 克隆并运行应用程序

   克隆仓库，安装依赖项，并创建 .env 文件：

   git clone https://github.com/ClickHouse/hn-news-analyzer.git
   cd hn-news-analyzer
   npm install
   cp .env.example .env
   

   ClickHouse 数据源默认指向公网只读演示集群，因此应用无需额外配置即可运行。启动它：

   ./run.sh
   

   打开 http://localhost:5001。你会看到年份选择器、汇总统计信息、活动图表、热门用户和域名表，以及一个搜索框。可以随意点一点：切换年份，深入查看具体帖子。

   此时，应用程序已经运行，但尚未接入遥测。ClickStack 中还没有数据：它正在等待遥测数据。这就是“之前”的状态。

2. 获取连接信息

   应用程序需要以下两个值才能连接到 collector：

   • OTEL_EXPORTER_OTLP_ENDPOINT：你的 collector 暴露的 OTLP 端点 (OTLP over HTTP 通常使用端口 4318) 。
   • OTEL_EXPORTER_OTLP_HEADERS：携带摄取令牌的授权请求头，格式为 authorization=<token>。

   打开 .env 并设置它们：

   OTEL_SERVICE_NAME=hn-analyzer-api
   OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-collector-endpoint>:4318
   OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
   

   SDK 使用 OTEL_EXPORTER_OTLP_HEADERS 为三种信号设置授权请求头：链路追踪、指标和日志。如果你的 collector 在本地运行且不强制启用身份验证，可以将该值留空 (OTEL_EXPORTER_OTLP_HEADERS=authorization=) ；但该变量必须存在，因为如果未设置，或其值完全为空，SDK 会完全跳过初始化。

3. 为应用添加插桩

   插桩分为三个部分：安装 SDKs、切换启动命令，以及启用浏览器 SDK。这些操作都不会改变应用程序的业务逻辑。

   安装 SDKs

   同时安装后端和浏览器 OpenTelemetry SDKs：

   npm install @hyperdx/node-opentelemetry @hyperdx/browser
   

   使用 opentelemetry-instrument CLI

   应用程序由 run.sh 启动，文件底部有两行 exec：一行启用，另一行被注释掉。切换启用的那一行，让 Node 通过 opentelemetry-instrument 启动：

    # BEFORE: plain node, no instrumentation, collector stays silent:
   -exec node scripts/entrypoint.js
   +# exec node scripts/entrypoint.js
   
    # AFTER: same source, wrapped by opentelemetry-instrument CLI.
   -# exec npx opentelemetry-instrument scripts/entrypoint.js
   +exec npx opentelemetry-instrument scripts/entrypoint.js
   

   这就是后端的全部改动。自动插桩会在进程启动时由 opentelemetry-instrument 加载。

   启用 Browser SDK

   要采集分布式链路追踪 (从浏览器到后端) 和会话回放，请在 src/web/telemetry.ts 中启用 Browser SDK。取消对 import 和 HyperDX.init({...}) 代码块的注释：

   import HyperDX from '@hyperdx/browser';
   
   export function initTelemetry(): void {
     HyperDX.init({
       url: __OTLP_ENDPOINT__,
       apiKey: __OTLP_AUTH_TOKEN__,
       service: 'hn-analyzer-web',
       tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
       consoleCapture: true,
       advancedNetworkCapture: true,
     });
   }
   

   无需额外修改 .env。__OTLP_ENDPOINT__ 和 __OTLP_AUTH_TOKEN__ 是由 vite.config.ts 注入的编译时常量：端点对应 OTEL_EXPORTER_OTLP_ENDPOINT，令牌则从 OTEL_EXPORTER_OTLP_HEADERS 中解析出来，与后端使用的值相同。

   摄取令牌会被打包进公开的浏览器 bundle 中，任何检查 Network 选项卡的人都可以读取它。

4. 生成流量并查看遥测数据

   重启应用程序，使新的启动命令和新构建的浏览器端打包产物生效：

   # Ctrl-C the previous run, then:
   ./run.sh
   

   重新加载浏览器选项卡，让 Vite 提供更新后的 bundle，然后多刷新应用几次、切换年份，再点开几篇 story 来生成流量。

   打开 ClickStack UI：

   1. 前往 搜索，将时间范围过滤到最近 5 分钟。hn-analyzer-api 的日志会不断流入。

   2. 点开一个请求，沿着 trace 向上查看。你会看到 Express handler span、一个指向 ClickHouse 集群且显示真实网络耗时的子 HTTP span，以及同一条 trace 上已关联的 console.log 记录。

   3. 打开 Session Replay，回放带可拖动进度条的浏览器会话视频，并与 trace 时间线同步。

   日志、指标、链路追踪和会话回放都会汇集到同一个 UI 中，共享同一种查询语言，并自动完成关联。

了解更多

• 会话回放：功能概览、SDK 选项和隐私控制。
• 会话回放演示：一个使用本地 ClickStack 实例的自包含演示。
• ClickStack 入门：部署 ClickStack 并摄取你的第一批数据。
• 所有示例数据集：其他示例数据集和相关指南。