使用 ClickStack 监控 Cloudflare 日志

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

摘要

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

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

​

概述

Cloudflare Logpush 可将 HTTP 请求日志导出到 Amazon S3 等目标端。将这些日志转发到 ClickStack 后，您可以：

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

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

替代方案：直接通过 HTTP 摄取

Cloudflare Logpush 也支持将日志直接推送到 HTTP 端点。由于 Cloudflare 将日志导出为以换行分隔的 JSON (NDJSON) ，而 ClickHouse 可通过 JSONEachRow 原生接收这种格式，因此您可以使用以下端点 URL 格式，将 Logpush 直接指向您的 ClickHouse Cloud HTTP 接口：

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 无法回填历史数据——因此，如果 ClickHouse 在推送期间不可用，这些日志将永久丢失。

​

与现有 Cloudflare Logpush 集成

本节假定你已将 Cloudflare Logpush 配置为将日志导出到 S3。否则，请先参考 Cloudflare 的 AWS S3 设置指南。

​

前置条件

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

1. ​

   配置 S3 身份验证

   ClickPipes 需要具备从您的 S3 bucket 读取数据的权限。请按照安全访问 S3 数据指南，配置基于 IAM 角色的访问或基于凭证的访问。

   有关 ClickPipes S3 身份验证和权限的完整详细信息，请参阅 S3 ClickPipes 参考文档。

2. ​

   创建 ClickPipes 作业

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

   连接：

   • 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

   摄取设置：

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

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

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

   schema 映射：

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

   点击 完成设置。

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

3. ​

   配置 HyperDX 数据源

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

   1. 打开 HyperDX → Team Settings → Sources

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

   设置	值
   名称	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

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

4. ​

   在 HyperDX 中验证数据

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

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

​

演示数据集

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

1. ​

   使用演示数据集创建 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 和静态资源请求、错误响应以及安全事件。

2. ​

   配置 HyperDX 数据源

   按照数据源配置步骤创建一个指向 cloudflare_http_logs 表的 HyperDX 数据源。如果你已在生产集成部分配置过该数据源，则无需执行此步骤。

3. ​

   验证演示数据

   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 状态码的严重性级别的日志条目。

   时区显示

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

​

仪表盘与可视化

1. ​

   仪表盘配置

2. ​

   导入仪表盘

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

   2. 上传 cloudflare-logs-dashboard.json → 完成导入
3. ​

   查看仪表盘

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

​

故障排查

​

数据未出现在 ClickHouse 中

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

SHOW TABLES FROM default LIKE 'cloudflare_http_logs';
SELECT count() FROM cloudflare_http_logs;

如果该表存在但为空，请前往 ClickPipes 检查是否有错误：ClickHouse Cloud 控制台 → 数据源 → 您的 ClickPipe → 日志。如需排查私有存储桶的身份验证问题，请参阅 S3 ClickPipes 访问控制文档。

​

HyperDX 中未显示日志

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

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

​

后续步骤

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

​

生产环境配置

本指南演示了如何使用公开的演示数据集摄取 Cloudflare 日志。对于生产环境部署，请配置 Cloudflare Logpush，将数据写入您自己的 S3 存储桶，并结合 基于 IAM 角色的身份验证 配置 ClickPipes，以确保访问安全。仅选择所需的 Logpush 字段，以降低存储成本和摄取量。在 Logpush 中启用按天划分的子文件夹，以便更好地组织文件，并在 ClickPipes 路径模式中使用 **/* 来匹配各级子目录中的文件。

有关高级配置选项 (包括用于处理历史回填和乱序文件的 基于 SQS 的无序摄取) ，请参阅 S3 ClickPipes 文档。