使用Prometheus监控Caddy

无论你是在云中运行数千个Caddy实例，还是在嵌入式设备上运行单个Caddy服务器，在某些时候你可能希望对Caddy正在做什么以及它持续了多长时间有一个高度的概览。 换句话说，你将希望能够 监控 Caddy。

启用指标

你需要先开启指标功能。

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

{
	metrics
}

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

如果你需要按主机维度拆分指标，可使用per_host：

{
	metrics {
		per_host
	}
}

如需在 catch-all HTTP 场景下也观测未显式配置的主机，可加入observe_catchall_hosts：

{
	metrics {
		per_host
		observe_catchall_hosts
	}
}

Prometheus

Prometheus是一个监控平台，它通过在这些目标上抓取指标 HTTP 端点来收集来自被监控目标的指标。 除了帮助你使用Grafana等仪表板工具显示指标外，Prometheus还用于报警。

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

如果你是 Prometheus 的新手，请阅读Prometheus文档！

要将 Prometheus 配置为从 Caddy 抓取，你需要一个类似于以下的 YAML 配置文件：

# prometheus.yaml
global:
  scrape_interval: 15s # default is 1 minute

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

然后你可以像这样启动Prometheus：

$ prometheus --config.file=prometheus.yaml

OpenTelemetry

Caddy也支持通过OTLP推送指标到OpenTelemetry端点，适用于OTLP-native观测栈（如OTel Collector、Grafana Alloy等）。

在metrics中启用otlp：

{
	metrics {
		otlp
	}
}

OTLP导出器使用标准OpenTelemetry环境变量进行配置，例如：

$ OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
	OTEL_METRICS_EXPORTER=otlp \
	caddy run

可通过OTEL_EXPORTER_OTLP_PROTOCOL=grpc改用gRPC；可通过OTEL_METRICS_EXPORTER=none临时关闭导出而不改Caddyfile。

Caddy的指标

与使用 Prometheus 监控的任何进程一样，Caddy 公开了一个 HTTP 端点，该端点以Prometheus展示格式进行响应。 Caddy 的 Prometheus 客户端还配置为在协商后以OpenMetrics展示格式 相应(即，如果Accept标头设置为application/openmetrics-text; version=0.0.1）。

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

你可以使用任何浏览器或HTTP客户端查看指标，例如curl：

$ 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
...

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

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

运行时指标

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

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

请参阅Go收集器、进程收集器](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewProcessCollector)和构建信息收集器文档。

管理API指标

这些是有助于监控 Caddy 管理 API 的指标。每个管理端点都经过检测以跟踪请求计数和错误。

这些指标的前缀是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.api.*命名空间中的模块。

caddy_admin_http_request_errors_total

管理端点中遇到的错误数量的计数器，包括admin.api.*命名空间中的模块。

HTTP中间件指标

所有 Caddy HTTP中间件处理程序都会自动检测，以确定请求延迟、首字节时间、错误和请求/响应正文大小。

对于下面的直方图指标，存储桶当前不可配置。 对于持续时间，使用默认的桶集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

衡量此服务器当前正在处理的请求数。

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

响应的第一个字节的时间直方图。

反向代理指标

reverse_proxy相关指标以caddy_reverse_proxy_*为前缀。

caddy_reverse_proxy_upstreams_healthy

用于表示上游是否健康（1为健康，0为不健康）的指标。可用于观察负载均衡池中后端可用性变化。

示例查询

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

例如，要查看每秒请求率，平均超过 5 分钟：

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

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

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"})