크로스플레인 메트릭 가이드

원문 보기 위키 갱신 2026.10.03

크로스플레인 메트릭 가이드 (Metrics)

크로스플레인은 환경의 효과적인 모니터링과 알림(alerting)을 위해 Prometheus 스타일의 메트릭을 생성합니다. 이 메트릭들은 잠재적인 문제를 식별하고 해결하는 데 필수적입니다. 이 페이지에서는 크로스플레인이 수집하는 모든 메트릭에 대한 설명을 제공합니다. 이 메트릭들을 이해하면 리소스의 상태와 성능을 유지하는 데 큰 도움이 됩니다.

출처: 문서

본문

이 문서는 크로스플레인 고유의 메트릭에 초점을 맞추며, 표준 Go 메트릭은 다루지 않습니다.

메트릭 내보내기(export)를 활성화하려면 helm 차트에서 --set metrics.enabled=true 옵션을 설정해야 합니다.

metrics:
  enabled: true

다음 Prometheus 어노테이션이 메트릭을 노출합니다.

prometheus.io/path: /metrics
prometheus.io/port: "8080"
prometheus.io/scrape: "true"

크로스플레인 코어 메트릭 (Crossplane core metrics)

크로스플레인 파드가 내보내는 메트릭입니다.

서킷 브레이커 메트릭 (Circuit breaker metrics)

서킷 브레이커(circuit breaker)는 복합 리소스(XR)별로 watch 이벤트를 모니터링하고 속도를 제한(rate-limit)함으로써 리컨실리에이션(reconciliation)이 반복되며 낭비되는 현상(thrashing)을 방지합니다. 크로스플레인 코어는 과도한 리컨실리에이션 활동을 식별하고 대응할 수 있도록 다음 메트릭을 내보냅니다.

모든 서킷 브레이커 메트릭에는 composite/. 형식(예: composite/xpostgresqlinstances.example.com)의 controller 라벨이 포함되어, 개별 XR 인스턴스의 높은 카디널리티(cardinality)를 만들지 않으면서 XRD별 가시성을 제공합니다.

circuit_breaker_opens_total

서킷 브레이커가 닫힘 상태에서 열림 상태로 전환되는 시점을 추적합니다. 값이 증가하면 XR이 과도한 watch 이벤트를 수신하여 스로틀링(throttling)이 발동되었음을 나타냅니다.

이 메트릭을 다음과 같은 용도로 사용할 수 있습니다.

리컨실리에이션 스래싱(thrashing)을 겪는 XR에 대한 알림
과도한 watch 이벤트를 받기 쉬운 XRD 유형 식별
서킷 브레이커 활성화 빈도 추적

예시 PromQL 쿼리:

# Rate of circuit breaker opens over 5 minutes
rate(circuit_breaker_opens_total[5m])

# Count of circuit breaker opens by controller
sum by (controller) (circuit_breaker_opens_total)

circuit_breaker_closes_total

서킷 브레이커가 열림 상태에서 닫힘 상태로 전환되는 시점을 추적합니다. 이는 XR이 과도한 watch 이벤트에서 회복되어 정상 운영으로 돌아왔음을 나타냅니다.

이 메트릭을 다음과 같은 용도로 사용할 수 있습니다.

리컨실리에이션 스래싱으로부터의 회복 모니터링
쿨다운 기간 이후 서킷 브레이커가 정상적으로 닫히는지 확인
서킷 브레이커 수명주기 추적

circuit_breaker_events_total

서킷 브레이커가 처리한 모든 watch 이벤트를 result에 따라 라벨링하여 추적합니다.

Allowed (허용): 회로가 닫힌 정상 운영 상태 — 이벤트가 리컨실리에이션으로 진행
Dropped (폐기): 회로가 완전히 열린 상태에서 이벤트가 차단됨 — 능동적 스로틀링을 나타냄
HalfOpenAllowed (반쯤 열림 허용): 회로가 반쯤 열린 상태에서 제한된 프로브 이벤트 — 회복 여부를 테스트하는 중

이 메트릭을 다음과 같은 용도로 사용할 수 있습니다.

XR 유형별 watch 이벤트 볼륨 추적
회로가 이벤트를 폐기하는 시점(능동적 스로틀링) 감지
높은 폐기 이벤트 비율에 대한 알림 (잠재적 문제 지표)
특정 컨트롤러에 가해지는 리컨실리에이션 압력 파악

예시 PromQL 쿼리:

# Rate of dropped events (active throttling), aggregated per controller
sum by (controller) (
  rate(circuit_breaker_events_total{result="Dropped"}[5m])
)

# Percentage of events being dropped
sum by (controller) (rate(circuit_breaker_events_total{result="Dropped"}[5m]))
/
sum by (controller) (rate(circuit_breaker_events_total[5m])) * 100

# Number of replicas per controller currently dropping events
count by (controller) (
  rate(circuit_breaker_events_total{result="Dropped"}[5m]) > 0
)

# Estimated number of circuit breaker opens over 5 minutes
sum by (controller) (
  increase(circuit_breaker_opens_total[5m])
)

# Alert condition: controllers under high watch pressure (severe overload)
sum by (controller) (
  rate(circuit_breaker_events_total{result="Dropped"}[5m])
) > 1

권장 알림 예시:

# Alert when circuit breaker is consistently dropping events
- alert: CircuitBreakerDropRatioHigh
  expr: |
    (
      sum by (controller)(rate(circuit_breaker_events_total{result="Dropped"}[5m]))
      /
      sum by (controller)(rate(circuit_breaker_events_total[5m]))
    ) > 0.2
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "High circuit breaker drop ratio for {{ $labels.controller }}"
    description: "More than 20% of events are being dropped by the circuit breaker for {{ $labels.controller }}, indicating sustained overload."

# Alert when circuit breaker opens frequently
- alert: CircuitBreakerFrequentOpens
  expr: |
    sum by (controller) (
      rate(circuit_breaker_opens_total[5m])
    ) * 3600 > 6
  for: 15m
  labels:
    severity: warning
  annotations:
    summary: "Frequent circuit breaker opens for {{ $labels.controller }}"
    description: "Circuit breaker for {{ $labels.controller }} is opening more than 6 times per hour, indicating reconciliation thrashing."

서킷 브레이커 기능과 구성에 대한 자세한 내용은 Troubleshooting - Circuit breaker 문서를 참고하세요.

프로바이더 메트릭 (Provider metrics)

크로스플레인 프로바이더가 내보내는 메트릭입니다. crossplane-runtime으로 빌드된 모든 프로바이더는 crossplane_managed_resource_* 메트릭을 내보냅니다.

프로바이더는 metrics 포트(기본값 8080)에서 메트릭을 노출합니다. 이 메트릭을 수집하려면 PodMonitor를 구성하거나 프로바이더의 DeploymentRuntimeConfig에 Prometheus 어노테이션을 추가하세요.

Upjet 프로바이더 메트릭 (Upjet provider metrics)

이 메트릭들은 Upjet 기반 프로바이더(예: provider-upjet-aws, provider-upjet-azure, provider-upjet-gcp)에서만 내보내집니다.

컨트롤러-런타임 및 쿠버네티스 클라이언트 메트릭 (Controller-runtime and Kubernetes client metrics)

이 메트릭들은 controller-runtime 프레임워크와 쿠버네티스 클라이언트 라이브러리에서 비롯됩니다. 크로스플레인과 프로바이더 모두 이 메트릭을 내보냅니다.