使用 ClickStack 监控 Nginx 链路追踪

使用 ClickStack 监控 Nginx 链路追踪

简而言之

使用 OpenTelemetry Nginx module，在 ClickStack 中采集来自 Nginx 的分布式链路追踪。包含演示数据集和预置仪表板。

​

与现有 Nginx 集成

本节介绍如何通过安装 OpenTelemetry 模块，并将其配置为向 ClickStack 发送链路追踪，为现有的 Nginx 部署添加分布式链路追踪。 如果您想在配置自己的现有环境之前先测试此集成，可以使用我们预先配置好的环境和样本数据，参见下一节。

前置条件

• 正在运行且可访问 OTLP 端点 (端口 4317/4318) 的 ClickStack 实例
• 已安装 Nginx (版本 1.18 或更高)
• 具有修改 Nginx 配置的 root 或 sudo 权限
• ClickStack 主机名或 IP 地址

1. ​

   安装 OpenTelemetry Nginx 模块

   为 Nginx 添加链路追踪的最简单方式，是使用内置 OpenTelemetry 支持的官方 Nginx image。

   使用 nginx:otel image

   将当前的 Nginx image 替换为启用了 OpenTelemetry 的版本：

   # 在你的 docker-compose.yml 或 Dockerfile 中
   image: nginx:1.27-otel
   

   该 image 已预装 ngx_otel_module.so，可直接使用。

   如果你是在 Docker 之外运行 Nginx，请参阅 OpenTelemetry Nginx documentation 获取手动安装说明。

2. ​

   配置 Nginx 将链路追踪发送到 ClickStack

   将 OpenTelemetry 配置添加到你的 nginx.conf 文件中。该配置会加载模块，并将链路追踪发送到 ClickStack 的 OTLP 端点。

   首先，获取你的 API key：

   1. 在你的 ClickStack URL 中打开 HyperDX
   2. 进入 Settings → API Keys
   3. 复制你的摄取 API key
   4. 将其设置为环境变量：export CLICKSTACK_API_KEY=your-api-key-here

   将以下内容添加到你的 nginx.conf 中：

   load_module modules/ngx_otel_module.so;
   
   events {
       worker_connections 1024;
   }
   
   http {
       # OpenTelemetry exporter 配置
       otel_exporter {
           endpoint <clickstack-host>:4317;
           header authorization ${CLICKSTACK_API_KEY};
       }
       
       # 用于标识此 nginx 实例的服务名称
       otel_service_name "nginx-proxy";
       
       # 启用链路追踪
       otel_trace on;
       
       server {
           listen 80;
           
           location / {
               # 为此 location 启用链路追踪
               otel_trace_context propagate;
               otel_span_name "$request_method $uri";
               
               # 将请求详细信息添加到链路追踪中
               otel_span_attr http.status_code $status;
               otel_span_attr http.request.method $request_method;
               otel_span_attr http.route $uri;
               
               # 你现有的 proxy 或应用配置
               proxy_pass http://your-backend;
           }
       }
   }
   

   如果在 Docker 中运行 Nginx，请将该环境变量传递给容器：

   services:
     nginx:
       image: nginx:1.27-otel
       environment:
         - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
       volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
   

   将 <clickstack-host> 替换为你的 ClickStack 实例主机名或 IP 地址。

   • 端口 4317 是 Nginx 模块使用的 gRPC 端点
   • otel_service_name 应该能够清晰描述你的 Nginx 实例 (例如 "api-gateway"、"frontend-proxy")
   • 请根据你的环境调整 otel_service_name，以便在 HyperDX 中更容易识别

   理解该配置

   会追踪什么： 发往 Nginx 的每个请求都会创建一个 trace span，显示：

   • 请求方法和路径
   • HTTP 状态码
   • 请求耗时
   • 时间戳

   Span attributes： otel_span_attr 指令会为每个 trace 添加元数据，使你能够在 HyperDX 中按状态码、方法、路由等对请求进行过滤和分析。

   完成这些更改后，测试你的 Nginx 配置：

   nginx -t
   

   如果测试通过，重新加载 Nginx：

   # 对于 Docker
   docker-compose restart nginx
   
   # 对于 systemd
   sudo systemctl reload nginx
   
3. ​

   在 HyperDX 中验证链路追踪

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

​

演示数据集

对于想在配置生产系统之前先测试 Nginx 链路追踪集成的用户，我们提供了一个预先生成的 Nginx 链路追踪 演示数据集，其中包含逼真的流量模式。

1. ​

   启动 ClickStack

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

   docker run --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   继续之前，请等待约 30 秒，让 ClickStack 完成初始化。

   • 端口 8080：HyperDX Web 界面
   • 端口 4317：OTLP gRPC 端点 (由 nginx 模块使用)
   • 端口 4318：OTLP HTTP 端点 (用于演示链路追踪)
2. ​

   下载样本数据集

   下载样本 链路追踪 文件，并将时间戳更新为当前时间：

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

   该数据集包含：

   • 1,000 个具有真实时序的 trace span
   • 9 个不同的端点，流量模式各不相同
   • ~93% 成功率 (200) 、~3% 客户端错误 (404) 、~4% 服务器错误 (500)
   • 延迟范围为 10ms 到 800ms
   • 保留原始流量模式，并整体移位到当前时间
3. ​

   将链路追踪发送到 ClickStack

   将你的 API key 设置为环境变量 (如果尚未设置) ：

   export CLICKSTACK_API_KEY=your-api-key-here
   

   获取你的 API key：

   1. 在你的 ClickStack URL 中打开 HyperDX
   2. 进入 Settings → API Keys
   3. 复制你的摄取 API key

   然后将链路追踪发送到 ClickStack：

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

   在 localhost 上运行

   此演示假定 ClickStack 在本地 localhost:4318 上运行。对于远程实例，请将 localhost 替换为你的 ClickStack 主机名。

   你应该会看到类似 {"partialSuccess":{}} 的响应，表示链路追踪已成功发送。全部 1,000 条链路追踪都会被摄取到 ClickStack 中。

4. ​

   在 HyperDX 中验证链路追踪

   1. 打开 HyperDX 并登录你的账户 (你可能需要先创建一个账户)
   2. 进入搜索视图，并将数据源设为 Traces
   3. 将时间范围设置为 2025-10-25 13:00:00 - 2025-10-28 13:00:00

   以下是你应当在搜索视图中看到的内容：

   时区显示

   HyperDX 会按浏览器的本地时区显示时间戳。演示数据覆盖 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)。较大的时间范围可确保无论你身处何地都能看到这些演示链路追踪。看到链路追踪后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

​

仪表盘和可视化

为帮助你开始使用 ClickStack 监控链路追踪，我们提供了用于链路追踪数据的关键可视化内容。

1. ​

   仪表盘配置

2. ​

   导入预置仪表盘

   1. 打开 HyperDX，进入“仪表盘”部分。
   2. 点击右上角省略号菜单中的“导入仪表盘”。

   3. 上传 nginx-trace-dashboard.json 文件，然后点击“完成导入”。
3. ​

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

   对于演示数据集，请将时间范围设置为 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (请根据你的本地时区进行调整) 。导入的仪表盘默认不会设置时间范围。

​

故障排查

​

HyperDX 中未显示任何链路追踪

确认是否已加载 nginx 模块：

nginx -V 2>&1 | grep otel

你应该会看到提及 OpenTelemetry 模块的内容。

检查网络连接：

telnet <clickstack-host> 4317

这应能成功连接到 OTLP gRPC 端点。

确认已设置 API key：

echo $CLICKSTACK_API_KEY

应输出你的 API key (不应为空) 。

检查 nginx 错误日志：

# 适用于 Docker
docker logs <nginx-container> 2>&1 | grep -i otel

# 适用于 systemd
sudo tail -f /var/log/nginx/error.log | grep -i otel

检查与 OpenTelemetry 相关的错误。

确认 nginx 是否正在接收请求：

# 检查访问日志以确认流量
tail -f /var/log/nginx/access.log

​

后续步骤

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

​

投入生产环境

本指南将链路追踪直接从 Nginx OpenTelemetry 模块发送到 ClickStack 的 OTLP 端点。对于生产环境部署，我们建议自行运行 OTel collector 作为网关，以提供批处理能力和弹性。有关生产环境配置，请参阅发送 OpenTelemetry 数据。