> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 ClickStack 监控 Nginx 链路追踪

> 使用 ClickStack 监控 Nginx 链路追踪

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **简而言之**

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

<div id="existing-nginx">
  ## 与现有 Nginx 集成
</div>

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

<div id="prerequisites">
  ##### 前置条件
</div>

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

<Steps>
  <Step>
    #### 安装 OpenTelemetry Nginx 模块

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

    ##### 使用 nginx:otel image

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

    ```yaml theme={null}
    # 在你的 docker-compose.yml 或 Dockerfile 中
    image: nginx:1.27-otel
    ```

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

    <Note>
      如果你是在 Docker 之外运行 Nginx，请参阅 [OpenTelemetry Nginx documentation](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx) 获取手动安装说明。
    </Note>
  </Step>

  <Step>
    #### 配置 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` 中：

    ```yaml theme={null}
    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，请将该环境变量传递给容器：

    ```yaml theme={null}
    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 地址。

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

    ##### 理解该配置

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

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

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

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

    ```bash theme={null}
    nginx -t
    ```

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

    ```bash theme={null}
    # 对于 Docker
    docker-compose restart nginx

    # 对于 systemd
    sudo systemctl reload nginx
    ```
  </Step>

  <Step>
    #### 在 HyperDX 中验证链路追踪

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=392f0f4ed941a5091c970090a6190769" alt="查看链路追踪" width="3838" height="1938" data-path="images/clickstack/nginx-traces-search-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## 演示数据集
</div>

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

<Steps>
  <Step>
    #### 启动 ClickStack

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

    ```bash theme={null}
    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 端点 (用于演示链路追踪)
  </Step>

  <Step>
    #### 下载样本数据集

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

    ```bash theme={null}
    # 下载 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
    * 保留原始流量模式，并整体移位到当前时间
  </Step>

  <Step>
    #### 将链路追踪发送到 ClickStack

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

    ```bash theme={null}
    export CLICKSTACK_API_KEY=your-api-key-here
    ```

    **获取你的 API key：**

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

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

    ```bash theme={null}
    curl -X POST http://localhost:4318/v1/traces \
      -H "Content-Type: application/json" \
      -H "Authorization: $CLICKSTACK_API_KEY" \
      -d @nginx-traces-sample.json
    ```

    <Info>
      **在 localhost 上运行**

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

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

  <Step>
    #### 在 HyperDX 中验证链路追踪

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

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

    <Info>
      **时区显示**

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=392f0f4ed941a5091c970090a6190769" alt="查看链路追踪" width="3838" height="1938" data-path="images/clickstack/nginx-traces-search-view.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## 仪表盘和可视化
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/zh/examples/nginx-traces-dashboard.json'} download="nginx-traces-dashboard.json" eventName="docs.nginx_traces_monitoring.dashboard_download">下载</TrackedLink> 仪表盘配置
  </Step>

  <Step>
    #### 导入预置仪表盘

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/import-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=cdfe26f160c1c080b995c8451311241d" alt="导入仪表盘" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/finish-nginx-traces-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=61bedea50b428001998f1096e1fe0761" alt="完成导入" width="3812" height="1906" data-path="images/clickstack/finish-nginx-traces-dashboard.png" />
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/nginx-traces-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=6496aed12bbbb3a91b7a162176469994" alt="示例仪表盘" width="3812" height="1906" data-path="images/clickstack/nginx-traces-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="no-traces">
  ### HyperDX 中未显示任何链路追踪
</div>

**确认是否已加载 nginx 模块：**

```bash theme={null}
nginx -V 2>&1 | grep otel
```

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

**检查网络连接：**

```bash theme={null}
telnet <clickstack-host> 4317
```

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

**确认已设置 API key：**

```bash theme={null}
echo $CLICKSTACK_API_KEY
```

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

**检查 nginx 错误日志：**

```bash theme={null}
# 适用于 Docker
docker logs <nginx-container> 2>&1 | grep -i otel

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

检查与 OpenTelemetry 相关的错误。

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

```bash theme={null}
# 检查访问日志以确认流量
tail -f /var/log/nginx/access.log
```

<div id="next-steps">
  ## 后续步骤
</div>

* 为关键指标 (错误率、延迟阈值) 配置[告警](/zh/clickstack/features/alerts)
* 针对特定用例 (API 监控、安全事件) 创建更多[仪表盘](/zh/clickstack/features/dashboards/overview)

<div id="going-to-production">
  ## 投入生产环境
</div>

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