Prometheus

本教程说明如何使用基于 Cloudflare Workers 和 Durable Objects 构建的开源工具 Cloudflare Prometheus Exporter ↗ 将 Cloudflare 指标导出到 Prometheus ↗。

概览

在设置 Cloudflare Prometheus Exporter 之前，请注意此集成：

适用于所有 Cloudflare 客户套餐（Free、Pro、Business 和 Enterprise）。Free 套餐的 zone 指标可用性有限。
基于 Cloudflare GraphQL Analytics API 和 REST API。
导出 90 多个 Prometheus 指标，涵盖请求、带宽、威胁、Workers、负载均衡器、SSL 证书、防火墙事件、健康检查、Magic Transit、Stream 等。
作为 Cloudflare Worker 运行，使用 Durable Objects 进行有状态计数器累积和后台刷新。
支持多账户设置，自动发现所有可访问的账户和 zone。

前提条件

在部署 exporter 之前，请确保：

拥有 Cloudflare 账户。
拥有具有所需权限的 Cloudflare API 令牌（见下方创建 API 令牌）。
拥有用于抓取 exporter 的 Prometheus 实例。

任务 1 - 部署 exporter

您可以使用一键部署或手动部署 exporter。

一键部署

选择下方按钮将 exporter 部署到您的 Cloudflare Workers 账户：

部署后，将 CLOUDFLARE_API_TOKEN 配置为 secret。可选配置 BASIC_AUTH_USER 和 BASIC_AUTH_PASSWORD，使用 HTTP Basic Auth 保护 exporter。

手动部署

git clone https://github.com/cloudflare/cloudflare-prometheus-exporter.git
cd cloudflare-prometheus-exporter
bun install
wrangler secret put CLOUDFLARE_API_TOKEN
bun run deploy

任务 2 - 创建 API 令牌

创建具有以下权限的 Cloudflare API 令牌：

使用预填权限创建令牌 ↗

权限	访问	必需
Zone > Analytics	Read	是
Account > Account Analytics	Read	是
Account > Workers Scripts	Read	是
Zone > SSL and Certificates	Read	可选
Zone > Firewall Services	Read	可选
Zone > Load Balancers	Read	可选
Account > Logs	Read	可选
Account > Magic Transit	Read	可选

任务 3 - 配置 Prometheus

在 Prometheus 配置中将 exporter 添加为 scrape 目标：

scrape_configs:
  - job_name: 'cloudflare'
    scrape_interval: 60s
    scrape_timeout: 30s
    static_configs:
      - targets: ['your-worker.your-subdomain.workers.dev']

使用 Basic Auth

如果在 exporter 上配置了 Basic Auth，请更新 Prometheus 配置：

scrape_configs:
  - job_name: 'cloudflare'
    scrape_interval: 60s
    scrape_timeout: 30s
    basic_auth:
      username: 'your-username'
      password: 'your-password'
    static_configs:
      - targets: ['your-worker.your-subdomain.workers.dev']

配置

配置按以下顺序解析：KV 覆盖 > 环境变量 > 默认值。您可以使用运行时配置 API 进行动态更改，无需重新部署。

在 wrangler.jsonc 中设置环境变量，或通过 wrangler secret put 设置：

变量	默认值	描述
`CLOUDFLARE_API_TOKEN`	-	Cloudflare API 令牌（secret）
`SCRAPE_DELAY_SECONDS`	`300`	获取指标前的延迟（数据传播）
`TIME_WINDOW_SECONDS`	`60`	查询时间窗口
`METRIC_REFRESH_INTERVAL_SECONDS`	`60`	后台刷新间隔
`CF_ACCOUNTS`	-	要包含的账户 ID，逗号分隔（默认：全部）
`CF_ZONES`	-	要包含的 zone ID，逗号分隔（默认：全部）
`METRICS_DENYLIST`	-	要排除的指标，逗号分隔
`EXCLUDE_HOST`	`false`	从指标中排除 host 标签
`METRICS_PATH`	`/metrics`	指标端点的自定义路径
`BASIC_AUTH_USER`	-	Basic Auth 用户名（secret）
`BASIC_AUTH_PASSWORD`	-	Basic Auth 密码（secret）

有关完整配置选项列表，请参阅 exporter README ↗。

端点

路径	方法	描述
`/`	GET	着陆页
`/metrics`	GET	Prometheus 指标
`/health`	GET	健康检查
`/config`	GET	获取所有运行时配置
`/config/:key`	PUT	设置配置覆盖（持久化在 KV 中）
`/config/:key`	DELETE	将配置键重置为默认值

可用指标

exporter 提供 90 多个指标，涵盖以下类别：

Zone 请求 - 总请求数、缓存请求数、按状态码、国家/地区、内容类型、HTTP 版本等的请求数。
Zone 带宽 - 总带宽、缓存带宽、按内容类型和国家/地区的带宽。
Zone 威胁 - 按国家/地区和类型的威胁计数。
Firewall - 按操作、来源和规则的防火墙事件。Bot 检测指标。
Workers - 按脚本的请求计数、错误计数、CPU 时间和持续时间。
Load balancers - 池健康状态、请求计数、RTT、steering policy 和源站权重。
Health checks - 健康检查事件、RTT、TTFB、TCP 连接时间和 TLS 握手时间。
SSL certificates - 按类型和颁发者的证书验证状态。
Cache - 缓存命中率和缓存未命中源站持续时间。
Error rates - 4xx/5xx 错误计数、边缘和源站错误率、源站响应持续时间。
Logpush - 账户和 zone 级别的失败作业计数。
Magic Transit - 隧道健康状态、SLO 状态和每个隧道的流量（比特和数据包）。
Magic Firewall - 每个规则的采样流量（比特和数据包）。
Network Analytics - Magic Transit、DDoS defense、IDPS、TCP protection 和 DNS protection 的流量。
Stream - 视频播放计数、观看时间、live input 指标。
Hostname metrics - 每个 hostname 的请求计数、延迟平均值和百分位数（需要 HOST_METRICS_ALLOWLIST）。

有关包含类型和标签的完整指标列表，请参阅 exporter README ↗。

Free 套餐 zone 限制

Cloudflare Free 套餐的 zone 无法访问 GraphQL Analytics API。exporter 会自动检测并跳过需要此 API 的指标的 Free 套餐 zone。

Free 套餐 zone 仍可导出：

cloudflare_zone_certificate_validation_status（SSL 证书）
cloudflare_zone_lb_origin_weight（负载均衡器权重，如已配置）

您可以使用 cloudflare_zones_skipped_free_tier 指标监控跳过的 zone。