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

本指南介绍如何使用 OpenTelemetry 为一个简单的 Node.js 应用埋点，并将其日志、指标和链路追踪发送到托管 ClickStack。后端的埋点无需更改应用源代码。 HackerNews Analyzer 是一个小型 Node.js 应用，用于查询托管在公网 ClickHouse 演示实例中的 HackerNews 数据集。每个图表、表格和搜索框背后都对应一个真实的 ClickHouse 查询，因此每次交互都会生成一条 trace，其中主 span 是后端发往 ClickHouse 的 HTTPS 调用。

前置条件

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

克隆并运行应用程序

克隆仓库，安装依赖项，并创建 .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 中还没有数据：它正在等待遥测数据。这就是“之前”的状态。

获取连接信息

应用程序需要以下两个值才能连接到 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 会完全跳过初始化。

为应用添加插桩

插桩分为三个部分：安装 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 选项卡的人都可以读取它。

生成流量并查看遥测数据

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

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

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

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

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

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

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

了解更多

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

​前置条件

​克隆并运行应用程序

​获取连接信息

​为应用添加插桩

​安装 SDKs

​使用 opentelemetry-instrument CLI

​启用 Browser SDK

​生成流量并查看遥测数据

​了解更多

前置条件

克隆并运行应用程序

获取连接信息

为应用添加插桩

安装 SDKs

使用 opentelemetry-instrument CLI

启用 Browser SDK

生成流量并查看遥测数据

了解更多