使用 ClickStack 监控 Node.js 链路追踪

本节介绍如何使用 OpenTelemetry 自动埋点为现有的 Node.js 应用程序添加分布式链路追踪。

如果您想先测试此集成，再配置自己的现有环境，可以使用我们预先配置的设置以及演示数据集部分中的样例数据进行测试。

• 正在运行且可访问 OTLP 端点 (端口 4317/4318) 的 ClickStack 实例
• 现有 Node.js 应用程序 (Node.js 14 或更高版本)
• npm 或 yarn 包管理器
• ClickStack 主机名或 IP 地址

安装并配置 OpenTelemetry

安装 @hyperdx/node-opentelemetry 包，并在应用程序启动时进行初始化。详细安装步骤请参阅 Node.js SDK 指南。

获取 ClickStack API key

需要一个 API key，用于将链路追踪发送到 ClickStack 的 OTLP 端点。

1. 在你的 ClickStack URL 中打开 HyperDX (例如 http://localhost:8080)
2. 如有需要，请创建账户或登录
3. 进入 Team Settings → API Keys
4. 复制你的 摄取 API key

运行你的应用程序

设置以下环境变量后，启动你的 Node.js 应用程序：

export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

生成一些流量

向你的应用程序发起请求以生成链路追踪：

# 简单请求
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# 模拟负载
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done

在 HyperDX 中验证链路追踪

配置完成后，登录 HyperDX 并确认链路追踪已正常上报。你应该会看到类似下面的内容。如果没有看到链路追踪，请尝试调整时间范围：

点击任意一个链路追踪，即可查看包含 spans、耗时和 attributes 的详细视图：

对于希望在为生产应用接入 Node.js trace 之前，先使用 ClickStack 测试 Node.js trace 的用户，我们提供了一个预先生成的 Node.js 应用 trace 样本数据集，其中包含逼真的流量模式。

下载样本数据集

下载样本链路追踪文件：

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

启动 ClickStack

如果你还没有运行 ClickStack，请使用以下命令启动：

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest

获取 ClickStack API key

用于将链路追踪发送到 ClickStack OTLP 端点的 API key。

1. 在你的 ClickStack URL 中打开 HyperDX (例如 http://localhost:8080)
2. 创建账户，或在需要时登录
3. 导航到 Team Settings → API Keys
4. 复制你的 摄取 API key

将你的 API key 设置为环境变量：

export CLICKSTACK_API_KEY=your-api-key-here

将链路追踪发送到 ClickStack

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

你应该会看到类似 {"partialSuccess":{}} 的响应，这表示链路追踪已成功发送。

在 HyperDX 中验证链路追踪

1. 打开 HyperDX，并登录你的账户 (你可能需要先创建账户)
2. 导航到 搜索 视图，并将 source 设置为 trace
3. 将时间范围设置为 2025-10-25 13:00:00 - 2025-10-28 13:00:00

为帮助你开始监控 Node.js 应用的性能，我们提供了一个预置仪表盘，其中包含关键的 trace 可视化内容。

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

1. 打开 HyperDX，进入 Dashboards 部分
2. 点击右上角的 导入仪表盘 (位于省略号菜单下)

3. 上传 nodejs-traces-dashboard.json 文件，然后点击 Finish Import

仪表盘创建后，所有可视化都会预先配置好

如果你已通过 curl 发送了链路追踪，但在 HyperDX 中看不到，请尝试再次发送一遍：

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

这是一个已知问题，会在通过 curl 使用演示方法时出现，但不会影响已完成遥测埋点的生产环境应用。

请确认环境变量已设置：

echo $CLICKSTACK_API_KEY
# 应输出您的 API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# 应输出 http://localhost:4318 或您的 ClickStack 主机地址

验证网络连接：

curl -v http://localhost:4318/v1/traces

应该可以成功连接到 OTLP 端点。

检查应用日志： 应用启动时，查找 OpenTelemetry 的初始化消息。HyperDX SDK 应会输出确认其已初始化的信息。

• 为关键指标 (错误率、延迟阈值) 设置告警
• 为特定用例 (API 监控、安全事件) 创建更多仪表盘

本指南使用的 HyperDX SDK 会将 trace 直接发送到 ClickStack 的 OTLP 端点。这种方式非常适合开发、测试以及中小型生产部署。 对于更大规模的生产环境，或者当您需要对遥测数据进行更多控制时，建议以 agent 方式部署您自己的 OpenTelemetry Collector。 有关生产部署模式和 collector 配置示例，请参阅 使用 OpenTelemetry 进行数据摄取。