使用 Prometheus 指标监控 Caddy

无论你是在云端运行数千个 Caddy 实例，还是在嵌入式设备上运行单个 Caddy 服务器，很可能你会希望某个时刻能够对 Caddy 的运行状况及其耗时有一个高层次的概览。换句话说，你会希望能够对 Caddy 进行监控。

启用指标

你需要开启指标功能。

如果使用 Caddyfile，请在 全局选项 中启用 metrics：

{
	metrics
}

如果使用 JSON，请在你的 apps > http > servers 配置 中添加 "metrics": {}。

要添加按主机的指标，可以插入 per_host 选项。主机特定的指标将带有 Host 标签。

{
	metrics {
		per_host
	}
}

Prometheus

Prometheus 是一个监控平台，通过抓取这些被监控目标上的指标 HTTP 端点来收集指标。除了帮助你使用像 Grafana 这样的仪表盘工具来展示指标外，Prometheus 也用于告警。

像 Caddy 一样，Prometheus 使用 Go 编写并作为单个二进制分发。要安装它，请参阅 Prometheus 安装文档，或者在 MacOS 上直接运行 brew install prometheus。

如果你对 Prometheus 完全陌生，请阅读 Prometheus 文档，否则继续往下读！

要配置 Prometheus 去抓取 Caddy，你需要一个类似于下面的 YAML 配置文件：

# prometheus.yaml
global:
  scrape_interval: 15s # 默认是 1 分钟

scrape_configs:
  - job_name: caddy
    static_configs:
      - targets: ['localhost:2019']

然后你可以这样启动 Prometheus：

$ prometheus --config.file=prometheus.yaml

Caddy 的指标

像任何使用 Prometheus 监控的进程一样，Caddy 会暴露一个 HTTP 端点，该端点以 Prometheus 展示格式 返回数据。Caddy 的 Prometheus 客户端也配置为在协商时响应 OpenMetrics 展示格式（也就是说，如果 Accept 头被设置为 application/openmetrics-text; version=0.0.1）。

默认情况下，在 admin API（即 http://localhost:2019/metrics）上有一个 /metrics 端点可用。但如果 admin API 被禁用或你希望在不同的端口或路径上监听，你可以使用 metrics 处理器 来配置它。

你可以使用任意浏览器或像 curl 这样的 HTTP 客户端查看这些指标：

$ curl http://localhost:2019/metrics
# HELP caddy_admin_http_requests_total Counter of requests made to the Admin API's HTTP endpoints.
# TYPE caddy_admin_http_requests_total counter
caddy_admin_http_requests_total{code="200",handler="metrics",method="GET",path="/metrics"} 2
# HELP caddy_http_request_duration_seconds Histogram of round-trip request durations.
# TYPE caddy_http_request_duration_seconds histogram
caddy_http_request_duration_seconds_bucket{code="308",handler="static_response",method="GET",server="remaining_auto_https_redirects",le="0.005"} 1
caddy_http_request_duration_seconds_bucket{code="308",handler="static_response",method="GET",server="remaining_auto_https_redirects",le="0.01"} 1
caddy_http_request_duration_seconds_bucket{code="308",handler="static_response",method="GET",server="remaining_auto_https_redirects",le="0.025"} 1
...

你会看到许多指标，大致分为 4 类：

• 运行时指标
• Admin API 指标
• HTTP 中间件指标
• 反向代理指标

运行时指标

这些指标涵盖了 Caddy 进程的内部情况，并由 Prometheus Go 客户端自动提供。它们以 go_* 和 process_* 为前缀。

注意，process_* 指标仅在 Linux 和 Windows 上收集。

请参阅 Go Collector、Process Collector 和 BuildInfo Collector 的文档。

Admin API 指标

这些指标有助于监控 Caddy admin API。每个 admin 端点都被加了监测，以跟踪请求计数和错误。

这些指标以 caddy_admin_* 为前缀。

例如：

$ curl -s http://localhost:2019/metrics | grep ^caddy_admin
caddy_admin_http_requests_total{code="200",handler="admin",method="GET",path="/config/"} 1
caddy_admin_http_requests_total{code="200",handler="admin",method="GET",path="/debug/pprof/"} 2
caddy_admin_http_requests_total{code="200",handler="admin",method="GET",path="/debug/pprof/cmdline"} 1
caddy_admin_http_requests_total{code="200",handler="load",method="POST",path="/load"} 1
caddy_admin_http_requests_total{code="200",handler="metrics",method="GET",path="/metrics"} 3

caddy_admin_http_requests_total

一个计数器，用于统计由 admin 端点处理的请求数量，包括 admin.api.* 命名空间中的模块。

caddy_admin_http_request_errors_total

一个计数器，用于统计 admin 端点遇到的错误次数，包括 admin.api.* 命名空间中的模块。

HTTP 中间件指标

所有 Caddy HTTP 中间件处理器都被自动加上了监测，用于确定请求延迟、首字节时间、错误以及请求/响应体大小。

对于下面的直方图指标，桶（buckets）当前不可配置。对于持续时间，使用默认的（prometheus.DefBuckets）桶集合（5ms、10ms、25ms、50ms、100ms、250ms、500ms、1s、2.5s、5s 和 10s）。对于大小，桶为 256b、1kiB、4kiB、16kiB、64kiB、256kiB、1MiB 和 4MiB。

caddy_http_requests_in_flight

一个 gauge，表示该服务器当前正在处理的请求数。

caddy_http_request_errors_total

一个计数器，统计在处理请求时遇到的中间件错误。

caddy_http_requests_total

一个 HTTP(S) 请求计数器。

caddy_http_request_duration_seconds

请求往返时长的直方图。

caddy_http_request_size_bytes

请求总（估计）大小的直方图。包括请求体。

caddy_http_response_size_bytes

返回响应体大小的直方图。

caddy_http_response_duration_seconds

响应首字节时间（time-to-first-byte）的直方图。

反向代理指标

caddy_reverse_proxy_upstreams_healthy

反向代理上游健康状况的 gauge。

值 0 表示上游不健康，值 1 表示上游健康。

示例查询

一旦 Prometheus 开始抓取 Caddy 的指标，你就可以开始看到一些关于 Caddy 性能的有趣指标。

例如，要查看以 5 分钟平均的每秒请求速率：

rate(caddy_http_requests_total{handler="file_server"}[5m])

要查看超过 100ms 延迟阈值的速率：

sum(rate(caddy_http_request_duration_seconds_count{server="srv0"}[5m])) by (handler)
-
sum(rate(caddy_http_request_duration_seconds_bucket{le="0.100", server="srv0"}[5m])) by (handler)

要查找 file_server 处理器的 95 百分位请求时长，可以使用如下查询：

histogram_quantile(0.95, sum(caddy_http_request_duration_seconds_bucket{handler="file_server"}) by (le))

或者查看 file_server 处理器上对成功 GET 请求的中位数响应大小（字节）：

histogram_quantile(0.5, caddy_http_response_size_bytes_bucket{method="GET", handler="file_server", code="200"})