使用 ClickStack 监控 Nginx 链路追踪

与现有 Nginx 集成

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

前置条件

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

安装 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，可直接使用。

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

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

首先，获取你的 API key：

在你的 ClickStack URL 中打开 HyperDX
进入 Settings → API Keys
复制你的摄取 API key
将其设置为环境变量：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 地址。

理解该配置

会追踪什么： 发往 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

在 HyperDX 中验证链路追踪

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

演示数据集

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

启动 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 端点 (用于演示链路追踪)

下载样本数据集

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

# 下载 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
保留原始流量模式，并整体移位到当前时间

将链路追踪发送到 ClickStack

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

export CLICKSTACK_API_KEY=your-api-key-here

获取你的 API key：

在你的 ClickStack URL 中打开 HyperDX
进入 Settings → API Keys
复制你的 摄取 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

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

在 HyperDX 中验证链路追踪

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

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

仪表盘和可视化

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

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

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

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

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

故障排查

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 数据。