메트릭으로 Caddy 모니터링하기

원문 보기 위키 갱신 2026.10.03

출처: Caddy 공식 문서

본문

클라우드에서 Caddy 인스턴스를 수천 개 실행하든, 임베디드 디바이스에서 단일 Caddy 서버를 실행하든, 언젠가는 Caddy가 무엇을 하고 있는지, 얼마나 걸리는지에 대한 높은 수준의 개요를 갖고 싶어질 거예요. 즉, Caddy를 모니터링할 수 있게 되고 싶을 거예요.

메트릭 활성화하기

메트릭을 켜야 해요.

Caddyfile을 사용한다면 전역 옵션에서 메트릭을 활성화해요:

{
	metrics
}

JSON을 사용한다면 apps > http > servers설정에 "metrics": {}를 추가해요.

호스트별 메트릭을 추가하려면 per_host 옵션을 넣을 수 있어요. 이제 호스트별 메트릭에 Host 태그가 붙어요.

{
	metrics {
		per_host
	}
}

이 설정은 구성된 호스트를 관찰해요. HTTPS 서버가 구성되어 있으면, 명시적으로 구성되지 않았더라도(예: on-demand TLS 설정) 호스트가 관찰돼요. HTTPS가 비활성화되면 잠재적인 무한 카디널리티 위험 때문에 구성된 호스트만 활성화돼요. HTTP 설정에서 구성되지 않은 호스트까지 포함해 모든 호스트를 관찰하려면 observe_catchall_hosts 옵션을 사용해요.

{
	metrics {
		per_host
		observe_catchall_hosts
	}
}

Prometheus

Prometheus는 대상의 메트릭 HTTP 엔드포인트를 스크래핑해 모니터링 대상에서 메트릭을 수집하는 모니터링 플랫폼이에요. Grafana 같은 대시보드 도구로 메트릭을 표시하는 것을 돕는 것 외에도, Prometheus는 알림(alerting)에도 사용돼요.

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는 OpenTelemetry Protocol(OTLP) 엔드포인트로도 메트릭을 푸시할 수 있어요. 이는 OpenTelemetry Collector, Grafana Alloy, Honeycomb, 또는 OTLP 메트릭을 직접 받는 다른 시스템 같은 OTLP 네이티브 관측 스택에 유용해요.

otlp 옵션으로 OTLP 메트릭 내보내기를 활성화해요:

{
	metrics {
		otlp
	}
}

OTLP 내보내기는 Caddy의 tracing 설정 스타일과 일치하는 표준 OpenTelemetry 환경 변수로 구성돼요. 예를 들어:

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

기본적으로 내보내기는 HTTP/protobuf를 통한 OTLP를 사용해요. gRPC를 사용하려면 OTEL_EXPORTER_OTLP_PROTOCOL=grpc로 설정하세요. 헤더, 엔드포인트, 프로토콜, 내보내기 선택, 수집 간격은 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_METRIC_EXPORT_INTERVAL 같은 환경 변수로 제어돼요.

Caddyfile을 바꾸지 않고 메트릭 내보내기를 비활성화하려면 OTEL_METRICS_EXPORTER=none으로 설정하세요.

OTLP 내보내기가 활성화되면 Caddy는 Prometheus 엔드포인트를 위해 수집한 것과 동일한 메트릭을 내보내요. 내보낸 메트릭에는 web_engine.name과 web_engine.version에 대한 리소스 속성이 포함돼요.

Caddy의 메트릭

Prometheus로 모니터링되는 어떤 프로세스와 마찬가지로 Caddy는 Prometheus exposition 형식으로 응답하는 HTTP 엔드포인트를 노출해요. Caddy의 Prometheus 클라이언트는 협상이 되면(즉 Accept 헤더가 application/openmetrics-text; version=0.0.1로 설정되면) OpenMetrics exposition 형식으로 응답하도록도 구성되어 있어요.

기본적으로 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를 모니터링하는 데 도움이 되는 메트릭이에요. 각 관리 엔드포인트는 요청 수와 오류를 추적하도록 계측되어 있어요.

이 메트릭은 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.* 네임스페이스의 모듈을 포함해 관리 엔드포인트가 처리한 요청 수의 카운터예요.

라벨	설명
`code`	HTTP 상태 코드
`handler`	핸들러 또는 모듈 이름
`method`	HTTP 메서드
`path`	관리 엔드포인트가 마운트된 URL 경로

`caddy_admin_http_request_errors_total`

admin.api.* 네임스페이스의 모듈을 포함해 관리 엔드포인트에서 발생한 오류 수의 카운터예요.

라벨	설명
`handler`	핸들러 또는 모듈 이름
`method`	HTTP 메서드
`path`	관리 엔드포인트가 마운트된 URL 경로

HTTP 미들웨어 메트릭

모든 Caddy HTTP 미들웨어 핸들러는 요청 지연 시간, 첫 바이트까지의 시간(time-to-first-byte), 오류, 요청/응답 본문 크기를 결정하기 위해 자동으로 계측돼요.

모든 미들웨어 핸들러가 계측되고 많은 요청이 여러 핸들러에 의해 처리되기 때문에, 모든 카운터를 그냥 합산하지 않도록 주의하세요.

아래 히스토그램 메트릭의 버킷은 현재 구성할 수 없어요. 기간의 경우 기본값(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`

이 서버가 현재 처리 중인 요청 수의 게이지예요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름

`caddy_http_request_errors_total`

요청을 처리하는 동안 발생한 미들웨어 오류의 카운터예요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름

`caddy_http_requests_total`

이루어진 HTTP(S) 요청의 카운터예요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름

`caddy_http_request_duration_seconds`

왕복 요청 기간의 히스토그램이에요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름
`code`	HTTP 상태 코드
`method`	HTTP 메서드

`caddy_http_request_size_bytes`

요청의 총(추정) 크기의 히스토그램이에요. 본문을 포함해요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름
`code`	HTTP 상태 코드
`method`	HTTP 메서드

`caddy_http_response_size_bytes`

반환된 응답 본문 크기의 히스토그램이에요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름
`code`	HTTP 상태 코드
`method`	HTTP 메서드

`caddy_http_response_duration_seconds`

응답의 첫 바이트까지의 시간(time-to-first-byte) 히스토그램이에요.

라벨	설명
`server`	서버 이름
`handler`	핸들러 또는 모듈 이름
`code`	HTTP 상태 코드
`method`	HTTP 메서드

리버스 프록시 메트릭

`caddy_reverse_proxy_upstreams_healthy`

리버스 프록시 업스트림 상태의 게이지예요.

값 0은 업스트림이 불건강하다는 뜻이고, 1은 업스트림이 건강하다는 뜻이에요.

라벨	설명
`upstream`	업스트림의 주소

샘플 쿼리

Prometheus가 Caddy의 메트릭을 스크래핑하기 시작하면 Caddy의 성능에 대한 흥미로운 메트릭을 볼 수 있어요.

위 설정으로 Caddy를 스크래핑하는 Prometheus 서버를 시작했다면, http://localhost:9090/graph의 Prometheus UI에 이 쿼리들을 붙여 넣어 보세요.

예를 들어 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"})

더 알아보기 (Learn more)

Caddy 공식 문서