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

# 使用 ClickStack 监控 Cloudflare 日志

> 使用 ClickPipes 通过 S3 将 Cloudflare Logpush 数据持续摄取到 ClickStack

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>
  **摘要**

  本指南介绍如何使用 ClickPipes 将 Cloudflare 日志摄取到 ClickStack。Cloudflare Logpush 会将日志写入 S3，而 ClickPipes 会持续将新文件摄取到 ClickHouse。不同于大多数通过 OpenTelemetry Collector 实现的 ClickStack 集成指南，本指南使用 [ClickPipes](/zh/integrations/clickpipes/home) 直接从 S3 拉取数据。

  如果你想在配置生产环境摄取之前先查看仪表盘，可使用演示数据集。
</Info>

<div id="overview">
  ## 概述
</div>

Cloudflare [Logpush](https://developers.cloudflare.com/logs/about/) 可将 HTTP 请求日志导出到 Amazon S3 等目标端。将这些日志转发到 ClickStack 后，您可以：

* 结合其他可观测性数据分析边缘流量、缓存性能和安全事件
* 使用 ClickHouse SQL 查询日志
* 将日志保留时间延长至超出 Cloudflare 的默认保留期限

本指南使用 [ClickPipes](/zh/integrations/clickpipes/home) 持续将 Cloudflare 日志文件从 S3 摄取到 ClickHouse。S3 在 Cloudflare 与 ClickHouse 之间充当持久缓冲层，提供精确一次语义和重放能力。

<Info>
  **替代方案：直接通过 HTTP 摄取**

  Cloudflare Logpush 也支持将日志直接推送到 [HTTP 端点](https://developers.cloudflare.com/logs/get-started/enable-destinations/http/)。由于 Cloudflare 将日志导出为以换行分隔的 JSON (NDJSON) ，而 ClickHouse 可通过 `JSONEachRow` 原生接收这种格式，因此您可以使用以下端点 URL 格式，将 Logpush 直接指向您的 ClickHouse Cloud HTTP 接口：

  ```text theme={null}
  https://YOUR_CLICKHOUSE_HOST:8443/?query=INSERT+INTO+cloudflare_http_logs+FORMAT+JSONEachRow&header_Authorization=Basic+BASE64_CREDENTIALS
  ```

  将 `YOUR_CLICKHOUSE_HOST` 替换为您的 ClickHouse Cloud 主机名，将 `BASE64_CREDENTIALS` 替换为经过 Base64 编码的凭据 (`echo -n 'default:YOUR_PASSWORD' | base64`) 。

  这种方式设置起来更简单 (无需配置 S3、SQS 或 IAM) ，但如果传输失败，Cloudflare Logpush [无法回填历史数据](https://developers.cloudflare.com/logs/logpush/)——因此，如果 ClickHouse 在推送期间不可用，这些日志将永久丢失。
</Info>

<div id="existing-cloudflare">
  ## 与现有 Cloudflare Logpush 集成
</div>

本节假定你已将 Cloudflare Logpush 配置为将日志导出到 S3。否则，请先参考 [Cloudflare 的 AWS S3 设置指南](https://developers.cloudflare.com/logs/get-started/enable-destinations/aws-s3/)。

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

* **ClickHouse Cloud 服务**已在运行 (ClickPipes 是 Cloud 独有功能，在 ClickStack OSS 中不可用)
* Cloudflare Logpush 正在持续将日志写入 S3 存储桶
* Cloudflare 写入日志所在的 S3 存储桶 名称和区域

<Steps>
  <Step>
    #### 配置 S3 身份验证

    ClickPipes 需要具备从您的 S3 bucket 读取数据的权限。请按照[安全访问 S3 数据](/zh/products/cloud/guides/data-sources/accessing-s3-data-securely)指南，配置基于 IAM 角色的访问或基于凭证的访问。

    有关 ClickPipes S3 身份验证和权限的完整详细信息，请参阅 [S3 ClickPipes 参考文档](/zh/integrations/clickpipes/object-storage/amazon-s3/overview#access-control)。
  </Step>

  <Step>
    #### 创建 ClickPipes 作业

    1. ClickHouse Cloud 控制台 → **数据源** → **创建 ClickPipe**
    2. **源**：Amazon S3

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/clickpipe-s3.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=7fcc3722d12d0b8f66bd62ad10e79b29" alt="Clickpipe s3" width="3834" height="1932" data-path="images/clickstack/cloudflare/clickpipe-s3.png" />

    **连接：**

    * **S3 文件路径**：您的 Cloudflare 日志存储桶路径，并使用通配符匹配文件。如果您在 Logpush 中启用了按日分的子文件夹，请使用 `**` 以匹配跨子目录的文件：
      * 无子文件夹：`https://your-bucket.s3.us-east-1.amazonaws.com/logs/*`
      * 按日分的子文件夹：`https://your-bucket.s3.us-east-1.amazonaws.com/logs/**/*`
    * **身份验证**：选择您的身份验证方法，并提供相应的凭据或 IAM Role ARN

    **摄取设置：**

    点击 **传入数据**，然后配置：

    * 打开 **持续摄取**
    * **排序**：词典序

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/continuous-ingestion.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=13b6b6243b6bdceb7bcb68b1c7d44ecf" alt="Continuous ingestion" width="3838" height="1938" data-path="images/clickstack/cloudflare/continuous-ingestion.png" />

    Cloudflare Logpush 使用基于日期的命名方式写入文件 (例如 `20250127/...`) ，天然符合词典序。ClickPipes 每 30 秒轮询一次新文件，并摄取所有名称大于上一个已处理文件的文件。

    **schema 映射：**

    点击 **解析信息**。ClickPipes 会对您的日志文件进行采样，并自动检测 schema。请检查映射后的列，并根据需要调整类型。为目标表定义一个 **排序键**——对于 Cloudflare 日志，一个不错的选择是 `(EdgeStartTimestamp, ClientCountry, EdgeResponseStatus)`。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/parse-information.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=814cda1893961c0afef80a2c230f0fb4" alt="Parse information" width="3838" height="1938" data-path="images/clickstack/cloudflare/parse-information.png" />

    点击 **完成设置**。

    <Note>
      首次创建时，ClickPipes 会先对指定路径中的**所有现有文件**执行初始加载，然后再切换到持续轮询。如果您的存储桶中积压了大量 Cloudflare 日志，此初始加载可能需要一些时间。
    </Note>
  </Step>

  <Step>
    #### 配置 HyperDX 数据源

    ClickPipes 会将 Cloudflare 日志摄取到一张扁平化表中，并使用 Cloudflare 的原生字段名。要在 HyperDX 中查看这些日志，请配置一个自定义数据源，将 Cloudflare 的列映射到 HyperDX 的日志视图。

    1. 打开 HyperDX → **Team Settings** → **Sources**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/add-source.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=01597132587a119cd3bc22464d8de06b" alt="添加数据源" width="1907" height="969" data-path="images/clickstack/cloudflare/add-source.png" />

    2. 点击 **Add source** 并按以下内容进行配置。点击 **Configure Optional Fields** 可查看所有字段：

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/configure-optional-fields.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=d796b5cfe6f74642ad426f4a1d0a0b61" alt="配置可选项" width="1882" height="1212" data-path="images/clickstack/cloudflare/configure-optional-fields.png" />

    | 设置           | 值                                                                                                                                                                                                                                                                                                                 |
    | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **名称**       | `Cloudflare Logs`                                                                                                                                                                                                                                                                                                 |
    | **源数据类型**    | 日志                                                                                                                                                                                                                                                                                                                |
    | **数据库**      | `default`                                                                                                                                                                                                                                                                                                         |
    | **表**        | `cloudflare_http_logs`                                                                                                                                                                                                                                                                                            |
    | **时间戳列**     | `toDateTime(EdgeStartTimestamp / 1000000000)`                                                                                                                                                                                                                                                                     |
    | **默认选择**     | `EdgeStartTimestamp, ClientRequestMethod, ClientRequestURI, EdgeResponseStatus, ClientCountry`                                                                                                                                                                                                                    |
    | **服务名称表达式**  | `'cloudflare'`                                                                                                                                                                                                                                                                                                    |
    | **日志级别表达式**  | `multiIf(EdgeResponseStatus >= 500, 'ERROR', EdgeResponseStatus >= 400, 'WARN', 'INFO')`                                                                                                                                                                                                                          |
    | **Body 表达式** | `concat(ClientRequestMethod, ' ', ClientRequestURI, ' ', toString(EdgeResponseStatus))`                                                                                                                                                                                                                           |
    | **日志属性表达式**  | `map('http.method', ClientRequestMethod, 'http.status_code', toString(EdgeResponseStatus), 'http.url', ClientRequestURI, 'client.country', ClientCountry, 'client.ip', ClientIP, 'cache.status', CacheCacheStatus, 'bot.score', toString(BotScore), 'cloudflare.ray_id', RayID, 'cloudflare.colo', EdgeColoCode)` |
    | **资源属性表达式**  | `map('cloudflare.zone', ClientRequestHost)`                                                                                                                                                                                                                                                                       |
    | **隐式列表达式**   | `concat(ClientRequestMethod, ' ', ClientRequestURI)`                                                                                                                                                                                                                                                              |

    3. 点击 **Save Source**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/save-source.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=cf5da5f4f49b97cb9c2a667aafdb4f1e" alt="保存数据源" width="1882" height="1678" data-path="images/clickstack/cloudflare/save-source.png" />

    这样就能将 Cloudflare 的原生列直接映射到 HyperDX 的日志查看器中，无需进行任何数据转换或重复存储。**Body** 会显示类似 `GET /api/v1/users 200` 的请求摘要，同时所有 Cloudflare 字段都可作为可搜索属性使用。
  </Step>

  <Step>
    #### 在 HyperDX 中验证数据

    前往 **搜索视图**，然后选择 **Cloudflare 日志** 数据源。将时间范围设置为覆盖你的数据所在时间段。你应该会看到包含以下内容的日志条目：

    * Body 列中的请求摘要 (例如 `GET /api/v1/users 200`)
    * 按 HTTP 状态码以不同颜色显示的严重级别 (2xx 为 INFO，4xx 为 WARN，5xx 为 ERROR)
    * 可搜索的属性，例如 `http.status_code`、`client.country`、`cache.status` 和 `bot.score`

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/search-view.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=2dc6c7ba71b45794405e000c190a8136" alt="搜索视图" width="3838" height="1938" data-path="images/clickstack/cloudflare/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/log-view.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=90b0df5fb795d24d46e3b14eff0f7d5f" alt="日志视图" width="3838" height="1938" data-path="images/clickstack/cloudflare/log-view.png" />
  </Step>
</Steps>

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

对于想要在配置生产环境 Cloudflare Logpush 之前先测试集成的用户，我们提供了一个包含逼真 HTTP 请求日志的演示数据集。

<Steps>
  <Step>
    #### 使用演示数据集创建 ClickPipe

    1. ClickHouse Cloud 控制台 → **数据源** → **Create ClickPipe**
    2. **Source**: Amazon S3
    3. **身份验证**: Public
    4. **S3 file path**: `https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/cloudflare/cloudflare-http-logs.json`
    5. 点击 **Incoming data**
    6. 选择 **JSON** 作为 format
    7. 点击 **Parse information** 并检查检测到的 schema
    8. 将 **Table name** 设置为 `cloudflare_http_logs`
    9. 点击 **Complete Setup**

    该数据集包含 5,000 条跨越 24 小时的 HTTP 请求日志，模式贴近真实场景，包括来自多个国家/地区的流量、缓存命中与未命中、API 和静态资源请求、错误响应以及安全事件。
  </Step>

  <Step>
    #### 配置 HyperDX 数据源

    按照[数据源配置步骤](#configure-source)创建一个指向 `cloudflare_http_logs` 表的 HyperDX 数据源。如果你已在生产集成部分配置过该数据源，则无需执行此步骤。
  </Step>

  <Step>
    #### 验证演示数据

    ```sql theme={null}
    SELECT count() FROM cloudflare_http_logs;
    -- 应返回 5000
    ```

    在 HyperDX 中进入 **Search** 视图，选择 **Cloudflare 日志** 数据源，并将时间范围设置为 **2026-02-23 00:00:00 - 2026-02-26 00:00:00**。

    你应当能看到包含请求摘要、可搜索的 Cloudflare attribute，以及基于 HTTP 状态码的严重性级别的日志条目。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/search-view.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=2dc6c7ba71b45794405e000c190a8136" alt="搜索视图" width="3838" height="1938" data-path="images/clickstack/cloudflare/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/log-view.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=90b0df5fb795d24d46e3b14eff0f7d5f" alt="日志视图" width="3838" height="1938" data-path="images/clickstack/cloudflare/log-view.png" />

    <Info>
      **时区显示**

      HyperDX 会按浏览器的本地时区显示时间戳。演示数据覆盖 **2026-02-24 00:00:00 - 2026-02-25 00:00:00 (UTC)**。较大的时间范围可确保无论你身处何地都能看到演示日志。看到日志后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。
    </Info>
  </Step>
</Steps>

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

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

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

    1. HyperDX → **仪表盘** → **导入仪表盘**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/import-dashboard.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=d7df19141a1f798301d7386d1a5ceffc" alt="导入仪表盘" width="3837" height="1398" data-path="images/clickstack/cloudflare/import-dashboard.png" />

    2. 上传 `cloudflare-logs-dashboard.json` → **完成导入**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/finish-import.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=9280cca2fafd36e111c1507c90508d3d" alt="导入仪表盘" width="3838" height="1934" data-path="images/clickstack/cloudflare/finish-import.png" />
  </Step>

  <Step>
    #### 查看仪表盘

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/cloudflare/example-dashboard.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=69f416ac24e538211ee200f12f71eab7" alt="示例仪表盘" width="3812" height="1934" data-path="images/clickstack/cloudflare/example-dashboard.png" />

    <Note>
      对于演示数据集，请将时间范围设置为 **2026-02-24 00:00:00 - 2026-02-25 00:00:00 (UTC)** (请根据您的本地时区调整) 。导入后的仪表盘默认不会指定时间范围。
    </Note>
  </Step>
</Steps>

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

<div id="no-data">
  ### 数据未出现在 ClickHouse 中
</div>

请确认该表已创建且包含数据：

```sql theme={null}
SHOW TABLES FROM default LIKE 'cloudflare_http_logs';
SELECT count() FROM cloudflare_http_logs;
```

如果该表存在但为空，请前往 ClickPipes 检查是否有错误：ClickHouse Cloud 控制台 → **数据源** → 您的 ClickPipe → **日志**。如需排查私有存储桶的身份验证问题，请参阅 [S3 ClickPipes 访问控制文档](/zh/integrations/clickpipes/object-storage/amazon-s3/overview#access-control)。

<div id="no-hyperdx">
  ### HyperDX 中未显示日志
</div>

如果数据已写入 ClickHouse，但在 HyperDX 中看不到，请检查数据源配置：

* 确认在 HyperDX → **团队设置** → **数据源** 中已存在 `cloudflare_http_logs` 对应的数据源
* 确保 **时间戳列** 设置为 `toDateTime(EdgeStartTimestamp / 1000000000)`——Cloudflare 的时间戳以纳秒为单位，需要先转换
* 确认 HyperDX 中选择的时间范围覆盖了这些数据。对于演示数据集，请使用 **2026-02-23 00:00:00 - 2026-02-26 00:00:00**

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

* 为安全事件设置[告警](/zh/clickstack/features/alerts) (WAF 拦截、机器人流量激增、错误率阈值)
* 根据您的数据量优化[数据保留策略](/zh/clickstack/managing/ttl)
* 为特定用例创建更多仪表盘 (API 性能、缓存优化、地域流量分析)

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

本指南演示了如何使用公开的演示数据集摄取 Cloudflare 日志。对于生产环境部署，请配置 Cloudflare Logpush，将数据写入您自己的 S3 存储桶，并结合 [基于 IAM 角色的身份验证](/zh/products/cloud/guides/data-sources/accessing-s3-data-securely) 配置 ClickPipes，以确保访问安全。仅选择所需的 [Logpush 字段](https://developers.cloudflare.com/logs/logpush/logpush-job/datasets/zone/http_requests/)，以降低存储成本和摄取量。在 Logpush 中启用按天划分的子文件夹，以便更好地组织文件，并在 ClickPipes 路径模式中使用 `**/*` 来匹配各级子目录中的文件。

有关高级配置选项 (包括用于处理历史回填和乱序文件的 [基于 SQS 的无序摄取](/zh/integrations/clickpipes/object-storage/amazon-s3/overview#continuous-ingestion-any-order)) ，请参阅 [S3 ClickPipes 文档](/zh/integrations/clickpipes/object-storage/amazon-s3/overview)。