使用 ClickStack 监控 Nginx 链路追踪

TL;DR

本指南演示如何从现有的 Nginx 部署中捕获分布式链路追踪（traces），并在 ClickStack 中对其进行可视化。您将学习如何：

为 Nginx 添加 OpenTelemetry 模块
配置 Nginx 将 traces 发送到 ClickStack 的 OTLP 端点
验证 traces 已出现在 HyperDX 中
使用预构建的仪表板可视化请求性能（延迟、错误、吞吐量）

如果您希望在为生产环境中的 Nginx 配置前先测试集成，可以使用提供的包含示例 traces 的演示数据集。

所需时间：5–10 分钟

与现有 Nginx 集成

本节介绍如何通过安装 OpenTelemetry 模块，并将其配置为向 ClickStack 发送追踪数据，为你现有的 Nginx 部署添加分布式追踪功能。如果你希望在配置自己的现有环境之前先测试集成效果，可以使用我们预先配置的环境和示例数据进行测试，详见以下章节。

前置条件

已运行的 ClickStack 实例，并且 OTLP 端点可访问（端口 4317/4318）
已安装 Nginx（版本 1.18 或更高）
拥有 root 或 sudo 权限以修改 Nginx 配置
ClickStack 主机名或 IP 地址

安装 OpenTelemetry Nginx 模块

为 Nginx 添加追踪的最简单方式是使用已内置 OpenTelemetry 支持的官方 Nginx 镜像。

使用 nginx:otel 镜像

将你当前的 Nginx 镜像替换为启用 OpenTelemetry 的版本：

# 在你的 docker-compose.yml 或 Dockerfile 中 \{#in-your-docker-composeyml-or-dockerfile}
image: nginx:1.27-otel

该镜像已预装 ngx_otel_module.so 模块，可直接使用。

注意

如果你在 Docker 之外运行 Nginx，请参考 OpenTelemetry Nginx 文档以获取手动安装说明。

配置 Nginx 将追踪发送至 ClickStack

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

首先，获取你的 API key：

通过 ClickStack 的 URL 打开 HyperDX
导航到 Settings → API Keys
复制你的 摄取 API key（Ingestion 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_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 属性： otel_span_attr 指令为每个 trace 添加元数据，使你可以按状态码、方法、路由等在 HyperDX 中过滤和分析请求。

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

nginx -t

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

# 对于 Docker \{#for-docker}
docker-compose restart nginx

# 对于 systemd \{#for-systemd}
sudo systemctl reload nginx

在 HyperDX 中验证追踪

配置完成后，登录 HyperDX 并验证追踪数据是否正常流入，你应当能看到类似如下的画面；如果没有看到追踪数据，尝试调整时间范围：

演示数据集

对于希望在配置生产系统之前先测试 nginx trace 集成的用户，我们提供了一份预先生成的 Nginx Traces 演示数据集，包含逼真的流量模式。

启动 ClickStack

如果您尚未运行 ClickStack，请使用以下命令启动：

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

等待约 30 秒，让 ClickStack 完全初始化后再继续。

端口 8080：HyperDX Web 界面
端口 4317：OTLP gRPC 端点（由 nginx 模块使用）
端口 4318：OTLP HTTP 端点（用于演示 traces）

下载示例数据集

下载示例 traces 文件，并将时间戳更新为当前时间：

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

该数据集包括：

1,000 个具有真实时序特征的 trace span
9 个不同的 endpoint，具有不同的流量模式
约 93% 成功率 (200)，约 3% 客户端错误 (404)，约 4% 服务器端错误 (500)
延迟范围从 10ms 到 800ms
保留原始流量模式，并整体平移到当前时间

将 traces 发送到 ClickStack

将您的 API key 设置为环境变量（如果尚未设置）：

export CLICKSTACK_API_KEY=your-api-key-here

获取您的 API key：

在您的 ClickStack URL 打开 HyperDX
导航到 Settings → API Keys
复制您的 摄取 API key（Ingestion API Key）

然后将 traces 发送到 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":{}} 的响应，表示 traces 已成功发送。所有 1,000 条 trace 都会被摄取到 ClickStack 中。

在 HyperDX 中验证 traces

打开 HyperDX 并登录您的账号（如有需要，您可能需要先创建一个账号）
导航到 Search 视图，并将 source 设置为 Traces
将时间范围设置为 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)。较宽的时间范围可以确保无论您身在何处，都能看到演示 traces。一旦看到这些 traces，您可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

仪表板与可视化

为帮助您开始使用 ClickStack 监控追踪数据，我们提供了一些用于 trace 数据的基础可视化配置。

下载仪表板配置

导入预构建仪表板

打开 HyperDX 并进入 Dashboards 页面。
点击右上角省略号菜单中的 "Import Dashboard"。

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

仪表板将被创建，并包含所有预先配置好的可视化视图。

注意

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

故障排查

在 HyperDX 中看不到任何追踪数据

确认已加载 nginx 模块：

nginx -V 2>&1 | grep otel

你应该会看到对 OpenTelemetry 模块的引用。

检查网络连通性：

telnet <clickstack-主机> 4317

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

验证已设置 API 密钥：

echo $CLICKSTACK_API_KEY

应当输出你的 API 密钥（不应为空）。

检查 nginx 错误日志：

# Docker 环境 \{#for-docker}
docker logs <nginx-container> 2>&1 | grep -i otel

# systemd 环境 \{#for-systemd}
sudo tail -f /var/log/nginx/error.log | grep -i otel

查找 OpenTelemetry 相关错误。

验证 nginx 是否正在接收请求：

# 检查访问日志以确认流量 \{#check-access-logs-to-confirm-traffic}
tail -f /var/log/nginx/access.log

后续步骤

如果你想进一步探索，可以尝试以下步骤来体验和优化你的仪表板：

为关键指标（错误率、延迟阈值）设置告警
为特定用例（API 监控、安全事件）创建额外的仪表板

与现有 Nginx 集成​

前置条件​

安装 OpenTelemetry Nginx 模块​

使用 nginx:otel 镜像​

配置 Nginx 将追踪发送至 ClickStack​

配置说明​

在 HyperDX 中验证追踪​

演示数据集​

启动 ClickStack​

下载示例数据集​

将 traces 发送到 ClickStack​

在 HyperDX 中验证 traces​

仪表板与可视化​

下载 仪表板配置​

导入预构建仪表板​

仪表板将被创建，并包含所有预先配置好的可视化视图。​

故障排查​

在 HyperDX 中看不到任何追踪数据​

后续步骤​