HackerNews Analyzer 演示

使用 agent 为 Node.js 应用添加插桩，并将日志、链路追踪、指标和会话回放发送至 ClickStack

简而言之

克隆 HackerNews Analyzer，在 .env 中填写您的 OTLP 端点和标记，然后粘贴 agent 提示词。后端无需导入 OpenTelemetry；agent 会在进程启动时配置 @hyperdx/node-opentelemetry。

所需时间：约 10 分钟

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

这与会话回放演示不同，后者为本地 Docker ClickStack 上仅在浏览器中运行的应用添加插桩。这里，您可以从同一应用获得后端自动插桩、ClickHouse 查询 span 和会话回放。

​

前置条件

• Node 18+ 和 npm
• ClickStack OTLP/HTTP 端点和摄取令牌：
  • **ClickHouse Cloud：**打开服务，然后依次选择 ClickStack → 配置 OpenTelemetry exporter → 环境变量。协议为 http/protobuf。请求头为 authorization=<ingestion token>，不带 Bearer 前缀。
  • **本地 collector：**使用 http://localhost:4318。如果 collector 未启用安全保护，请将 authorization= 留空。

​

克隆代码仓库

克隆 HackerNews Analyzer，安装依赖项并复制环境变量模板：

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

你将在后续步骤中填写 .env，然后在此目录中为应用添加插桩。

​

为应用添加插桩

1. 运行应用

   在克隆的 hn-news-analyzer 目录中启动应用。ClickHouse 数据源默认使用公网只读演示集群，因此无需额外配置即可运行：

   ./run.sh
   

   打开 http://localhost:5001。您将看到年份选择器、汇总统计信息、活动图表、热门用户和域表，以及搜索框。您可以随意点击浏览：切换年份，深入查看新闻条目。

   

   此时，应用程序虽在运行，但尚未插桩。ClickStack 尚未显示任何数据，正等待遥测数据。

2. 配置环境

   SDK 会读取标准的 OpenTelemetry exporter 变量，而非在源代码中硬编码。打开 .env 并设置：

   OTEL_SERVICE_NAME=hn-analyzer-api
   OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
   OTEL_TRACES_EXPORTER=otlp
   OTEL_METRICS_EXPORTER=otlp
   OTEL_LOGS_EXPORTER=otlp
   

   OTEL_EXPORTER_OTLP_ENDPOINT 是 OTLP/HTTP 端点 (端口 4318) 。OTEL_EXPORTER_OTLP_HEADERS 是授权请求头，格式为 authorization=<token>，不带 Bearer 前缀。

   如果 collector 未强制实施身份验证，请将标记留空 (OTEL_EXPORTER_OTLP_HEADERS=authorization=) 。该变量仍必须存在；如果未设置或完全为空，SDK 将跳过初始化。

   Browser SDK 会复用这些值。vite.config.ts 会在构建时将端点和标记写入公开 bundle，因此请使用一次性的摄取标记，而不要使用生产环境标记。

3. 为应用程序添加遥测埋点

   选择一种方式。三种方式最终都会得到同一个完成插桩的应用程序。

   使用智能体插桩

   克隆仓库并填写 .env 后，在该目录中将以下提示粘贴给编程智能体，为应用程序添加插桩。

   手动插桩

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

   ​

   安装 Node SDK

   npm install @hyperdx/node-opentelemetry
   

   ​

   在 run.sh 中启用包装器

   run.sh 的末尾有两行 exec。注释掉普通的 node 行，并取消注释插桩后的那一行：

    # 之前：普通 node，未插桩：
   -exec node scripts/entrypoint.js
   +# exec node scripts/entrypoint.js
   
    # 之后：相同的源代码，由 opentelemetry-instrument 包装：
   -# exec npx opentelemetry-instrument scripts/entrypoint.js
   +exec npx opentelemetry-instrument scripts/entrypoint.js
   

   请始终通过 scripts/entrypoint.js 启动。该垫片会调用 require('console')，从而使控制台捕获能够包装 console.log。将 opentelemetry-instrument 直接指向 dist/server/index.js 虽然会发送链路追踪，但会悄然丢失日志。

   ​

   启用浏览器 SDK

   npm install @hyperdx/browser
   

   在 src/web/telemetry.ts 中，取消注释导入语句、HyperDX.init({...}) 块，以及 recordAction() 中的 HyperDX.addAction：

   -// import HyperDX from '@hyperdx/browser';
   +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,
   -  // });
   +  HyperDX.init({
   +    url: __OTLP_ENDPOINT__,
   +    apiKey: __OTLP_AUTH_TOKEN__,
   +    service: 'hn-analyzer-web',
   +    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
   +    consoleCapture: true,
   +    advancedNetworkCapture: true,
   +  });
    }
   

   __OTLP_ENDPOINT__ 和 __OTLP_AUTH_TOKEN__ 是编译时常量，vite.config.ts 会使用后端所用的相同 OTEL_EXPORTER_OTLP_* 值将其注入。

   摄取令牌会被嵌入公开的浏览器包中，任何查看 Network 选项卡的人都可以读取它。请使用一次性令牌。

   使用预先插桩的分支

   若要跳过插桩并直接使用已插桩的应用程序，请检出 instrumented 分支。

   git checkout instrumented
   npm install
   

   除非你想移除 SDK，否则不要在此分支上运行 ./reset.sh。

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

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

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

   确认启动横幅中针对 /v1/traces、/v1/metrics 和 /v1/logs 显示了三行 “Health check passed”。重新加载浏览器选项卡，让 Vite 提供更新后的 bundle，然后切换年份并点击文章以生成流量。

   打开 ClickStack UI：

   1. 前往 搜索，筛选最近 5 分钟的数据。hn-analyzer-api 的日志会不断流入。

   

   2. 点击某个 request，然后沿 trace 向上查看。你将看到 Express handler span、一个指向 sql-clickhouse.clickhouse.com 且包含实际网络耗时的子 HTTP span，以及同一 trace 上关联的 console.log 记录。

   

   3. 打开 Session Replay，播放与 trace 时间线同步、可拖动浏览的浏览器 session 视频。

   

   日志、指标、链路追踪和 session replay 都会进入同一 UI，使用相同的 query language，并自动关联。

​

了解更多

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