모니터링 & 메트릭

모니터링 & 메트릭 (Monitoring & Metrics)

Cilium과 Hubble은 모두 Prometheus 메트릭을 제공하도록 구성할 수 있어요. Prometheus는 플러그형 메트릭 수집·저장 시스템이며 Grafana(메트릭 시각화 프론트엔드)의 데이터 소스 역할을 합니다. Cilium 메트릭과 Hubble 메트릭은 서로 독립적으로 활성화할 수 있습니다.

출처: Monitoring & Metrics

본문

Cilium과 Hubble 메트릭은 서로 독립적으로 활성화할 수 있어요.

Cilium 메트릭 (Cilium Metrics)

Cilium 메트릭은 Cilium 자체의 상태, 즉 cilium-agent, cilium-envoy, cilium-operator 프로세스에 대한 인사이트를 제공해요. Prometheus 메트릭을 활성화한 상태로 Cilium을 실행하려면 prometheus.enabled=true Helm 값을 설정해 배포하세요.

Cilium 메트릭은 cilium_ Prometheus 네임스페이스 아래로 내보내집니다. Envoy 메트릭은 envoy_ Prometheus 네임스페이스 아래로 내보내지며, 그중 Cilium이 정의한 메트릭은 envoy_cilium_ 네임스페이스 아래로 내보내져요. Kubernetes에서 실행·수집할 때는 파드 이름과 네임스페이스로 태깅됩니다.

설치 (Installation)

cilium-agent(Envoy 포함)의 메트릭은 Helm 값 prometheus.enabled=true로 활성화할 수 있어요. cilium-operator 메트릭은 기본적으로 활성화되어 있으며, 비활성화하려면 Helm 값 operator.prometheus.enabled=false로 설정하세요.

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true

Cilium 메트릭 스크레이핑

Prometheus 포트 구성

포트는 각각 prometheus.port, envoy.prometheus.port, operator.prometheus.port로 구성할 수 있어요.

메트릭이 활성화되고 ServiceMonitor가 비활성화된 경우(hubble.metrics.serviceMonitor.enabled: false), 모든 Cilium 컴포넌트는 다음과 같은 어노테이션을 갖게 됩니다. 이 어노테이션은 Prometheus에게 메트릭을 스크레이프할지 여부를 알리는 데 사용할 수 있어요.

ServiceMonitor가 활성화된 경우(hubble.metrics.serviceMonitor.enabled: true)에는 이 어노테이션이 생략되고, Prometheus는 ServiceMonitor 리소스를 통해 메트릭을 발견합니다.

prometheus.io/scrape: true
prometheus.io/port: 9962

Envoy 메트릭을 수집하기 위해 Cilium 차트는 prometheus.io/scrape:'true' 어노테이션이 설정된 cilium-agent라는 Kubernetes headless 서비스를 만듭니다:

prometheus.io/scrape: true
prometheus.io/port: 9964

각 컴포넌트는 Prometheus 스크레이프·포트 어노테이션을 하나만 가질 수 있기 때문에, 다른 Cilium 컴포넌트 외에 이 추가 headless 서비스가 필요해요.

scrape_configs 섹션에 다음 옵션을 설정하면 Prometheus가 Cilium과 Envoy 메트릭을 자동으로 수집합니다:

scrape_configs:
- job_name: 'kubernetes-pods'
  kubernetes_sd_configs:
  - role: pod
  relabel_configs:
    - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
      action: keep
      regex: true
    - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
      action: replace
      regex: ([^:]+)(?::\d+)?;(\d+)
      replacement: ${1}:${2}
      target_label: __address__

Prometheus Operator ServiceMonitor

prometheus.serviceMonitor.enabled=true, envoy.prometheus.serviceMonitor.enabled=true, 또는 operator.prometheus.serviceMonitor.enabled=true를 각각 설정하면 Prometheus Operator ServiceMonitor를 자동으로 생성할 수 있어요.

Hubble 메트릭 (Hubble Metrics)

Cilium 메트릭이 Cilium 자체의 상태를 모니터링하게 하는 반면, Hubble 메트릭은 Cilium이 관리하는 Kubernetes 파드의 연결성과 보안과 관련된 네트워크 동작을 모니터링하게 해줘요.

일부 메트릭은 추가 옵션으로 구성할 수도 있어요. 사용 가능한 전체 메트릭과 옵션 목록은 Hubble 내보내기 메트릭 섹션을 참고하세요.

정적 또는 동적 exporter

Hubble 메트릭은 정적(static) 또는 동적(dynamic) exporter로 구성할 수 있어요.

동적 메트릭 exporter를 사용하면 에이전트 재시작 없이 정의된 메트릭을 필요에 따라 변경할 수 있습니다.

정적 메트릭 exporter로 설치

정적 exporter가 활성화된 Hubble 메트릭으로 Cilium을 배포하려면 hubble.enabled=true로 Hubble을 활성화하고 hubble.metrics.enabled를 통해 활성화할 Hubble 메트릭 집합을 제공해야 해요.

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true \
   --set hubble.enabled=true \
   --set hubble.metrics.enableOpenMetrics=true \
   --set hubble.metrics.enabled="{dns,drop,tcp,flow,port-distribution,icmp,httpV2:exemplars=true;labelsContext=source_ip\,source_namespace\,source_workload\,destination_ip\,destination_namespace\,destination_workload\,traffic_direction}"

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true \
   --set hubble.enabled=true \
   --set hubble.metrics.enableOpenMetrics=true \
   --set hubble.metrics.enabled="{dns,drop,tcp,flow,port-distribution,icmp,httpV2:exemplars=true;labelsContext=source_ip\,source_namespace\,source_workload\,destination_ip\,destination_namespace\,destination_workload\,traffic_direction}"

동적 메트릭 exporter로 설치

동적 Hubble 메트릭이 활성화된 Cilium을 배포하려면 hubble.enabled=true와 hubble.metrics.dynamic.enabled=true로 Hubble을 활성화해야 해요.

이 예제에서는 exporter를 활성화하기 전에 메트릭 집합이 담긴 ConfigMap을 적용하지만, 원하는 메트릭 집합(과 ConfigMap)은 설치 중에 만들 수도 있어요.

Helm Reference 문서를 참고하세요 (hubble.metrics.dynamic.* 키).

apiVersion: v1
kind: ConfigMap
metadata:
  name: cilium-dynamic-metrics-config
  namespace: kube-system
data:
  dynamic-metrics.yaml: |
    metrics:
      - name: dns
      - contextOptions:
        - name: sourceContext
          values:
          - workload-name
          - reserved-identity
        - name: destinationContext
          values:
          - workload-name
          - reserved-identity
        name: flow
      - name: drop
      - name: tcp
      - contextOptions:
        - name: sourceContext
          values:
          - workload-name
          - reserved-identity
        name: icmp
      - contextOptions:
        - name: exemplars
          values:
          - true
        - name: labelsContext
          values:
          - source_ip
          - source_namespace
          - source_workload
          - destination_ip
          - destination_namespace
          - destination_workload
          - traffic_direction
        - name: sourceContext
          values:
          - workload-name
          - reserved-identity
        - name: destinationContext
          values:
          - workload-name
          - reserved-identity
        name: httpV2
      - contextOptions:
        - name: sourceContext
          values:
          - app
          - workload-name
          - pod
          - reserved-identity
        - name: destinationContext
          values:
          - app
          - workload-name
          - pod
          - dns
          - reserved-identity
        - name: labelsContext
          values:
          - source_namespace
          - destination_namespace
        excludeFilters:
        - destination_pod:
          - default/
        name: policy

ConfigMap을 배포하세요:

kubectl apply -f dynamic-metrics.yaml

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true \
   --set hubble.enabled=true \
   --set hubble.metrics.enableOpenMetrics=true \
   --set hubble.metrics.enabled=[] \
   --set hubble.metrics.dynamic.enabled=true \
   --set hubble.metrics.dynamic.config.configMapName=cilium-dynamic-metrics-config \
   --set hubble.metrics.dynamic.config.createConfigMap=false

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set prometheus.enabled=true \
   --set operator.prometheus.enabled=true \
   --set hubble.enabled=true \
   --set hubble.metrics.enableOpenMetrics=true \
   --set hubble.metrics.enabled=[] \
   --set hubble.metrics.dynamic.enabled=true \
   --set hubble.metrics.dynamic.config.configMapName=cilium-dynamic-metrics-config \
   --set hubble.metrics.dynamic.config.createConfigMap=false

Hubble 메트릭 스크레이핑

Prometheus 포트 구성

Hubble 메트릭의 포트는 hubble.metrics.port Helm 값으로 구성할 수 있어요.

Hubble 메트릭을 TLS로 활성화하는 방법은 문서의 Hubble Metrics TLS 및 인증 섹션을 참고하세요.

Note

HTTP 같은 L7 메트릭은 레이어 7 프로토콜 가시성을 활성화한 파드에 대해서만 내보내져요.

비어 있지 않은 hubble.metrics.enabled Helm 값으로 배포하면, Cilium 차트는 prometheus.io/scrape:'true' 어노테이션이 설정된 hubble-metrics라는 Kubernetes headless 서비스를 만듭니다:

prometheus.io/scrape: true
prometheus.io/port: 9965

Prometheus의 scrape_configs 섹션에 다음 옵션을 설정하면 엔드포인트의 모든 Hubble 메트릭을 자동으로 스크레이프합니다:

scrape_configs:
  - job_name: 'kubernetes-endpoints'
    scrape_interval: 30s
    kubernetes_sd_configs:
      - role: endpoints
    relabel_configs:
      - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      - source_labels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
        action: replace
        target_label: __address__
        regex: (.+)(?::\d+);(\d+)
        replacement: $1:$2

Prometheus Operator ServiceMonitor

hubble.metrics.serviceMonitor.enabled=true를 설정하면 Prometheus Operator ServiceMonitor를 자동으로 생성할 수 있어요.

OpenMetrics

추가로 hubble.metrics.enableOpenMetrics=true를 설정해 OpenMetrics를 선택할 수 있어요. OpenMetrics를 활성화하면 Hubble 메트릭 엔드포인트가 클라이언트가 명시적으로 요청할 때 OpenMetrics 형식으로 메트릭을 내보내는 것을 지원합니다.

OpenMetrics를 사용하면 Exemplars 같은 추가 기능을 지원해서, 내보낸 메트릭에 trace ID를 임베드해 메트릭을 트레이스와 연결할 수 있어요.

Prometheus는 OpenMetrics를 활용하도록 구성되어야 하며, exemplars 저장 기능이 활성화된 경우에만 exemplar를 스크레이프합니다.

OpenMetrics는 메트릭 이름과 라벨에 몇 가지 추가 요구사항을 부과하므로 이 기능은 현재 선택적(opt-in)입니다. 다만 모든 Hubble 메트릭이 OpenMetrics 요구사항을 충족한다고 생각합니다.

Cluster Mesh API Server 메트릭

Cluster Mesh API Server 메트릭은 clustermesh-apiserver 프로세스, kvstoremesh 프로세스(활성화된 경우), 사이드카 etcd 인스턴스의 상태에 대한 인사이트를 제공해요. Cluster Mesh API Server 메트릭은 cilium_clustermesh_apiserver_ Prometheus 네임스페이스 아래로 내보내집니다. KVStoreMesh 메트릭은 cilium_kvstoremesh_ 네임스페이스로, etcd 메트릭은 etcd_ 네임스페이스로 내보내져요.

설치 (Installation)

다음 값을 설정해서 다양한 Cluster Mesh API Server 컴포넌트의 메트릭을 활성화할 수 있어요:

clustermesh-apiserver: clustermesh.apiserver.metrics.enabled=true
kvstoremesh: clustermesh.apiserver.metrics.kvstoremesh.enabled=true
sidecar etcd 인스턴스: clustermesh.apiserver.metrics.etcd.enabled=true

Helm Repository

helm install cilium cilium/cilium --version 1.20.2 \
   --namespace kube-system \
   --set clustermesh.useAPIServer=true \
   --set clustermesh.apiserver.metrics.enabled=true \
   --set clustermesh.apiserver.metrics.kvstoremesh.enabled=true \
   --set clustermesh.apiserver.metrics.etcd.enabled=true

OCI Registry

helm install cilium oci://quay.io/cilium/charts/cilium 1.20.2 \
   --namespace kube-system \
   --set clustermesh.useAPIServer=true \
   --set clustermesh.apiserver.metrics.enabled=true \
   --set clustermesh.apiserver.metrics.kvstoremesh.enabled=true \
   --set clustermesh.apiserver.metrics.etcd.enabled=true

포트는 각각 clustermesh.apiserver.metrics.port, clustermesh.apiserver.metrics.kvstoremesh.port, clustermesh.apiserver.metrics.etcd.port로 구성할 수 있어요.

clustermesh.apiserver.metrics.serviceMonitor.enabled=true를 설정하면 Prometheus Operator ServiceMonitor를 자동으로 생성할 수 있어요.

예제 Prometheus & Grafana 배포

실행 중인 Prometheus와 Grafana 스택이 없다면 다음으로 스택을 배포할 수 있어요:

kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/1.20.2/examples/kubernetes/addons/prometheus/monitoring-example.yaml

이것은 cilium-monitoring 네임스페이스에서 Prometheus와 Grafana를 실행해요. Cilium 또는 Hubble 메트릭을 활성화했다면 Prometheus가 자동으로 스크레이프합니다. 그런 다음 Grafana를 노출해 브라우저로 접근할 수 있어요.

kubectl -n cilium-monitoring port-forward service/grafana --address 0.0.0.0 --address :: 3000:3000

브라우저를 열고 http://localhost:3000/에 접근하세요.

메트릭 레퍼런스 (Metrics Reference)

cilium-agent

구성 (Configuration)

메트릭을 노출하려면 cilium-agent를 --prometheus-serve-addr 옵션으로 실행하세요. 이 옵션은 IP:Port 쌍을 받지만 빈 IP(예: :9962)를 전달하면 서버가 모든 사용 가능한 인터페이스에 바인딩됩니다(컨테이너에는 보통 하나만 있어요).

메트릭을 커스터마이즈하려면 +/- 접두사를 사용해 특정 메트릭을 활성화/비활성화하세요. 대규모 클러스터에서는 cilium_node_health_connectivity_status와 cilium_node_health_connectivity_latency_seconds 같은 고카디널리티(high-cardinality) 메트릭을 비활성화하는 것을 고려하세요.

Helm

prometheus.metrics 값을 사용하세요:

helm install cilium cilium/cilium 1.20.2 \
    --namespace kube-system \
    --set prometheus.enabled=true \
    --set prometheus.metrics="{-cilium_node_health_connectivity_status,-cilium_node_health_connectivity_latency_seconds}"

CLI

--metrics 플래그를 사용하세요:

cilium-agent --prometheus-serve-addr=:9962 \
    --metrics="-cilium_node_health_connectivity_status -cilium_node_health_connectivity_latency_seconds"

기능 메트릭 (Feature Metrics)

Cilium Feature Metrics는 cilium_feature Prometheus 네임스페이스 아래로 내보내집니다.

다음 테이블은 기능 메트릭을 네 개 그룹으로 분류해요:

고급 연결 및 로드 밸런싱 (adv_connect_and_lb) 이 범주에는 Bandwidth Manager, BGP, Envoy Proxy, Cluster Mesh 같은 고급 네트워킹 및 로드 밸런싱 기능이 포함됩니다.
컨트롤 플레인 (controlplane) 이 메트릭들은 identity 할당 모드와 IP 주소 관리(IPAM)를 포함한 컨트롤 플레인 구성을 추적해요.
데이터패스 (datapath) 이 그룹의 메트릭은 인터넷 프로토콜 모드, 체이닝 모드, 네트워크 모드 같은 데이터패스 구성을 모니터링해요.
네트워크 정책 (network_policies) 이 그룹은 Cilium Network Policies, Host Firewall, DNS 정책, Mutual Auth를 포함한 정책 적용 관련 메트릭을 다룹니다.

예를 들어 Cilium 에이전트에서 Bandwidth Manager가 활성화되었는지 확인하려면 cilium_feature_adv_connect_and_lb_bandwidth_manager_enabled 메트릭을 관찰하세요. 모든 메트릭은 cilium_feature + 그룹 이름 + 메트릭 이름 형식을 따릅니다. 값 0은 기능이 비활성화됨을, 1은 활성화됨을 나타냅니다.

Note

"counter" 유형의 메트릭은 에이전트가 해당 오브젝트(예: 네트워크 정책)를 처리했지만 적극적으로 적용 중이 아닐 수 있어요. 이 메트릭들은 오브젝트가 수신·처리되었는지 관찰하는 용도이며, 반드시 적용되었다는 뜻은 아닙니다.

`adv_connect_and_lb`

`controlplane`

`datapath`

`network_policies`

내보내기 메트릭 (Exported Metrics)

Endpoint

Services

Cluster health

Node Connectivity

Clustermesh

Datapath

IPsec

eBPF

bpf_maps_virtual_memory_max_bytes와 bpf_progs_virtual_memory_max_bytes는 둘 다 현재 Cilium이 직접 관리하거나 관리하지 않는 eBPF의 시스템 전체 메모리 사용량을 보고해요. 이는 향후 변경되어 Cilium이 직접 관리하는 eBPF 메모리 사용량만 보고할 수 있습니다.

Drops/Forwards (L3/L4)

Policy

Policy L7 (HTTP/FQDN)

Identity

Events external to Cilium

Controllers

controllers_group_runs_total 메트릭은 시스템 내 각 컨트롤러의 성공·실패 횟수를 컨트롤러 그룹 이름과 완료 상태로 구분해 보고해요. 컨트롤러가 많기 때문에 이 메트릭은 컨트롤러별로 활성화됩니다. 이는 controller-group-metrics 구성 플래그나 prometheus.controllerGroupMetrics helm 값으로 전달되는 allow-list로 구성돼요. 현재 권장되는 기본 그룹 이름 집합은 Cilium Helm 차트의 values 파일에서 찾을 수 있어요. 특별한 이름 "all"과 "none"이 지원됩니다.

SubProcess

| 이름 | 라벨 | 기본값 | 설명 | | subprocess_start_total | subsystem | Enabled | Cilium이 하위 프로세스를 시작한 횟수 |

Kubernetes

Kubernetes Rest Client

Kubernetes workqueue

IPAM

KVstore

Agent

| 이름 | 라벨 | 기본값 | 설명 | | api_process_time_seconds | path, method, return_code | Enabled | cilium-agent로의 모든 API 호출 처리 시간, API 메서드·경로·반환 HTTP 코드로 구분됨 |

FQDN

Hive

Jobs

API Rate Limiting

BGP Control Plane

모든 메트릭은 BGP Control Plane이 활성화된 경우에만 활성화됩니다.

cilium-operator

구성 (Configuration)

cilium-operator는 --enable-metrics 옵션으로 실행해 메트릭을 제공하도록 구성할 수 있어요. 기본적으로 operator는 9963 포트에서 메트릭을 노출하며, 포트는 --operator-prometheus-serve-addr 옵션으로 변경할 수 있어요.

기능 메트릭 (Feature Metrics)

Cilium Operator Feature Metrics는 cilium_operator_feature Prometheus 네임스페이스 아래로 내보내집니다.

다음 테이블은 기능 메트릭을 다음과 같은 그룹으로 분류해요:

고급 연결 및 로드 밸런싱 (adv_connect_and_lb) 이 범주에는 Gateway API, Ingress Controller, LB IPAM, Node IPAM, L7 Aware Traffic Management 같은 고급 네트워킹·로드 밸런싱 기능이 포함됩니다.

예를 들어 Cilium operator에서 Gateway API가 활성화되었는지 확인하려면 cilium_operator_feature_adv_connect_and_lb_gateway_api_enabled 메트릭을 관찰하세요. 모든 메트릭은 cilium_operator_feature + 그룹 이름 + 메트릭 이름 형식을 따릅니다. 값 0은 비활성화, 1은 활성화를 나타냅니다.

Note

"counter" 유형의 메트릭은 operator가 해당 오브젝트(예: 네트워크 정책)를 처리했지만 적극적으로 적용 중이 아닐 수 있어요. 이 메트릭들은 오브젝트가 수신·처리되었는지 관찰하는 용도이며, 반드시 적용되었다는 뜻은 아닙니다.

`adv_connect_and_lb`

| 이름 | 라벨 | 가능한 라벨 값 | 설명 | 유형 | | gateway_api_enabled | 없음 | 없음 | operator에서 GatewayAPI 활성화됨 | gauge | | ingress_controller_enabled | 없음 | 없음 | operator에서 IngressController 활성화됨 | gauge | | l7_aware_traffic_management_enabled | 없음 | 없음 | operator에서 L7 Aware Traffic Management 활성화됨 | gauge | | lb_ipam_enabled | 없음 | 없음 | operator에서 LB IPAM 활성화됨 | gauge | | node_ipam_enabled | 없음 | 없음 | operator에서 Node IPAM 활성화됨 | gauge |

내보내기 메트릭 (Exported Metrics)

대부분의 메트릭은 cilium_operator_ Prometheus 네임스페이스 아래로 내보내집니다. 일부 메트릭은 대신 cilium_ 네임스페이스(에이전트와 공유) 아래로 내보내지며, 관련 섹션에서 별도로 표시됩니다.

BGP Control Plane Operator

모든 메트릭은 BGP Control Plane이 활성화된 경우에만 활성화됩니다.

IPAM

Note

IPAM 메트릭은 AWS, Alibabacloud 또는 Azure IPAM 플러그인을 사용할 때만 모두 Enabled예요.

| 이름 | 라벨 | 기본값 | 설명 | | ipam_ip_allocation_ops | subnet_id | Enabled | IP 할당 연산 수 | | ipam_ip_release_ops | subnet_id | Enabled | IP 해제 연산 수 | | ipam_interface_creation_ops | subnet_id | Enabled | 인터페이스 생성 연산 수 | | ipam_release_duration_seconds | type, status, subnet_id | Enabled | IP 또는 인터페이스 해제 지연(초) | | ipam_allocation_duration_seconds | type, status, subnet_id | Enabled | IP 또는 인터페이스 할당 지연(초) | | ipam_nodes | category | Enabled | category별 노드 수 { total | in-deficit | at-capacity } | | ipam_resync_total | | Enabled | 외부 IPAM API와의 동기화 연산 수 | | ipam_api_duration_seconds | operation, response_code | Enabled | 외부 IPAM API와의 상호작용 시간 | | ipam_api_rate_limit_duration_seconds | operation | Enabled | 외부 IPAM API 접근 중 rate limiting 시간 | | ipam_available_ips | target_node | Enabled | 노드의 사용 가능한 IP 수(플러그인별 NIC/주소 제한 고려) | | ipam_used_ips | target_node | Enabled | 노드에서 현재 사용 중인 IP 수 | | ipam_needed_ips | target_node | Enabled | 노드의 할당을 충족하는 데 필요한 IP 수 |

LB-IPAM

Note

이 메트릭들은 cilium_operator_가 아니라 cilium_ 네임스페이스(예: cilium_lbipam_conflicting_pools) 아래로 내보내집니다.

Controllers

| 이름 | 라벨 | 기본값 | 설명 | | controllers_group_runs_total | status, group_name | Enabled | 컨트롤러 그룹 이름으로 구분된 컨트롤러 프로세스 실행 횟수 |

CiliumEndpointSlices (CES)

CES 컨트롤러에는 CES 업데이트를 처리하는 여러 내부 큐가 있다는 점을 참고하세요. 이 큐들이 내보내는 상세 메트릭은 아래의 내부 WorkQueues 섹션에서 찾을 수 있어요.

Unmanaged Pods

| 이름 | 라벨 | 기본값 | 설명 | | unmanaged_pods | | Enabled | Cilium operator가 관리하지 않는 것으로 관찰된 총 파드 수 |

"Double Write" Identity Allocation Mode

"Double Write" identity 할당 모드가 활성화되면 다음 메트릭을 사용할 수 있어요:

Identity Garbage Collection

Identity 가비지 컬렉션은 operator에서 실행돼요. 이 메트릭들은 CRD identity 할당 모드를 사용할 때만 보고됩니다.

Identity Management Mode

내부 WorkQueues (Internal WorkQueues)

Operator는 다양한 작업 처리를 관리하기 위해 내부 큐를 사용해요. 현재 Cilium Node Synchronizer 큐와 Cilium EndpointSlice Controller 큐만 아래 메트릭을 보고합니다.

MCS-API

Clustermesh

Note

clustermesh_remote_clusters, clustermesh_remote_cluster_failures, clustermesh_remote_cluster_last_failure_ts, clustermesh_remote_cluster_readiness_status, clustermesh_remote_cluster_cache_revocations는 cilium_operator_가 아니라 cilium_ 네임스페이스(예: cilium_clustermesh_remote_clusters) 아래로 내보내집니다. 이 섹션의 나머지 메트릭(clustermesh_remote_cluster_services, clustermesh_remote_cluster_endpoint_slices, clustermesh_remote_cluster_service_exports)은 cilium_operator_ 아래로 내보내집니다.

Hubble

구성 (Configuration)

Hubble 메트릭은 cilium-agent 안에서 실행되는 Hubble 인스턴스가 제공해요. 이것을 구성하는 커맨드라인 옵션은 --enable-hubble, --hubble-metrics-server, --hubble-metrics입니다. --hubble-metrics-server는 IP:Port 쌍을 받지만 빈 IP(예: :9965)를 전달하면 서버가 모든 인터페이스에 바인딩됩니다. --hubble-metrics는 공백으로 구분된 메트릭 목록을 받아요. 또한 Hubble 메트릭을 TLS로 수신 대기하고 선택적으로 mTLS로 인증받도록 구성할 수도 있어요. 자세한 내용은 Hubble Metrics TLS 및 인증을 참고하세요.

일부 메트릭은 메트릭별로 세미콜론으로 구분된 추가 옵션을 받을 수 있어요. 예를 들어 --hubble-metrics="dns:query;ignoreAAAA http:destinationContext=workload-name"는 dns 메트릭에 query와 ignoreAAAA 옵션을, http 메트릭에 destinationContext=workload-name 옵션을 적용합니다.

컨텍스트 옵션 (Context Options)

Hubble 메트릭은 컨텍스트 옵션을 통한 구성을 지원해요. 모든 메트릭에 지원되는 컨텍스트 옵션:

sourceContext — egress·ingress 트래픽 모두에 대한 메트릭의 source 라벨을 구성.
sourceEgressContext — egress 트래픽에 대한 메트릭의 source 라벨을 구성 (sourceContext보다 우선).
sourceIngressContext — ingress 트래픽에 대한 메트릭의 source 라벨을 구성 (sourceContext보다 우선).
destinationContext — egress·ingress 트래픽 모두에 대한 메트릭의 destination 라벨을 구성.
destinationEgressContext — egress 트래픽에 대한 메트릭의 destination 라벨을 구성 (destinationContext보다 우선).
destinationIngressContext — ingress 트래픽에 대한 메트릭의 destination 라벨을 구성 (destinationContext보다 우선).
labelsContext — 메트릭에서 활성화할 라벨 목록을 구성.

특정 메트릭에만 있는 컨텍스트 옵션도 있어요. 각 메트릭에서 어떤 옵션을 사용할 수 있는지는 개별 메트릭 문서를 참고하세요.

각 컨텍스트 옵션에 대한 자세한 내용은 아래를 참고하세요.

대부분의 Hubble 메트릭은 sourceContext와 destinationContext 옵션을 사용해 소스 및/또는 대상 컨텍스트를 라벨로 추가하도록 구성할 수 있어요. 가능한 값은:

소스 및/또는 대상 컨텍스트를 지정할 때 | 기호로 구분해 여러 컨텍스트를 지정할 수 있어요. 여러 개를 지정하면 첫 번째 비어 있지 않은 값이 메트릭에 라벨로 추가됩니다. 예를 들어 flow:destinationContext=dns|ip 메트릭 구성은 먼저 대상의 DNS 이름을 라벨로 사용하려고 시도하고, 대상의 DNS 이름을 알 수 없으면 대상의 IP 주소를 대신 사용해요.

Note

identity 라벨 목록에 여러 예약 라벨이 포함되는 3가지 경우가 있어요:

reserved:kube-apiserver와 reserved:host

reserved:kube-apiserver와 reserved:remote-node

reserved:kube-apiserver와 reserved:world

이 3가지 경우 모두 reserved-identity 컨텍스트는 reserved:kube-apiserver를 반환합니다.

Hubble 메트릭은 메트릭에 추가할 라벨 목록을 제공하는 labelsContext로도 구성할 수 있어요. sourceContext와 destinationContext는 서로 다른 값을 같은 메트릭 라벨에 넣는 반면, labelsContext는 서로 다른 라벨 값에 넣어요.

흐름 컨텍스트를 지정할 때 , 기호로 구분해 여러 값을 지정할 수 있어요. 나열된 모든 라벨은 비어 있어도 메트릭에 포함됩니다. 예를 들어 http:labelsContext=source_namespace,source_pod 구성은 모든 Hubble HTTP 메트릭에 source_namespace와 source_pod 라벨을 추가해요.

Note

메트릭 카디널리티를 제한하기 위해 Hubble은 파드 삭제 1분 후 그 특정 파드에 바인딩된 데이터 시리즈를 제거해요. 메트릭이 특정 파드에 바인딩된 것으로 간주되는 조건 중 하나:

sourceContext가 pod로 설정되고 메트릭 시리즈의 source 라벨이 <pod_namespace>/<pod_name>과 일치

destinationContext가 pod로 설정되고 메트릭 시리즈의 destination 라벨이 <pod_namespace>/<pod_name>과 일치

labelsContext가 source_namespace와 source_pod를 모두 포함하고 메트릭 시리즈 라벨이 삭제된 파드의 네임스페이스·이름과 일치

labelsContext가 destination_namespace와 destination_pod를 모두 포함하고 메트릭 시리즈 라벨이 삭제된 파드의 네임스페이스·이름과 일치

내보내기 메트릭 (Exported Metrics)

Hubble 메트릭은 hubble_ Prometheus 네임스페이스 아래로 내보내집니다.

lost events

이 메트릭은 다른 메트릭들과 달리 네트워크 흐름과 직접 연결되지 않아요. 다른 메트릭 중 하나라도 활성화되면 활성화됩니다.

| 이름 | 라벨 | 기본값 | 설명 | | lost_events_total | source | Enabled | 손실된 이벤트 수 |

라벨

source는 손실된 이벤트의 소스를 식별하며, 다음 중 하나:
- perf_event_ring_buffer
- observer_events_queue
- hubble_ring_buffer

`dns`

옵션

| 옵션 키 | 옵션 값 | 설명 | | query | N/A | 쿼리를 "query" 라벨로 포함 | | ignoreAAAA | N/A | 모든 AAAA 요청/응답 무시 |

이 메트릭은 컨텍스트 옵션을 지원합니다.

`drop`

| 이름 | 라벨 | 기본값 | 설명 | | drop_total | reason, protocol | Disabled | 드랍 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`flow`

| 이름 | 라벨 | 기본값 | 설명 | | flows_processed_total | protocol, type, subtype, verdict | Disabled | 처리된 총 흐름 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`flows-to-world`

이 메트릭은 대상 identity에 reserved:world 라벨을 포함하는 모든 비응답(non-reply) 흐름을 계산해요. 기본적으로 드랍된 흐름은 드랍 이유가 Policy denied인 경우에만 계산됩니다. 모든 드랍 흐름을 계산하려면 any-drop 옵션을 설정하세요.

| 이름 | 라벨 | 기본값 | 설명 | | flows_to_world_total | protocol, verdict | Disabled | reserved:world로 가는 총 흐름 수 |

옵션

| 옵션 키 | 옵션 값 | 설명 | | any-drop | N/A | 드랍 이유와 무관하게 드랍된 모든 흐름 계산 | | port | N/A | 대상 포트를 "port" 라벨로 포함 | | syn-only | N/A | TCP 흐름에서 비응답 SYN만 계산 |

이 메트릭은 컨텍스트 옵션을 지원합니다.

`http`

Deprecated, 대신 httpV2를 사용하세요. 이 메트릭들은 httpV2와 동시에 활성화할 수 없어요.

라벨

method는 요청/응답의 HTTP 메서드.
protocol은 요청의 HTTP 프로토콜 (예: HTTP/1.1, HTTP/2).
status는 응답의 HTTP 상태 코드.
reporter는 요청/응답의 출처. 클라이언트에서 시작되었으면 client, 서버에서 시작되었으면 server, 출처를 알 수 없으면 unknown으로 설정.

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`httpV2`

httpV2는 기존 http 메트릭의 업데이트된 버전이에요. 이 메트릭들은 http와 동시에 활성화할 수 없습니다.

주요 차이점은 http_requests_total과 http_responses_total이 통합되었고 응답 흐름 데이터를 사용한다는 점이에요.

또한 http_request_duration_seconds 메트릭의 source/destination 관련 라벨은 이제 요청 관점에서 봅니다. http 메트릭에서는 응답 흐름 데이터를 사용해 source/destination이 바뀌었지만, httpV2에서는 이를 올바르게 반영합니다.

라벨

method는 요청/응답의 HTTP 메서드.
protocol은 요청의 HTTP 프로토콜 (예: HTTP/1.1, HTTP/2).
status는 응답의 HTTP 상태 코드.
reporter는 요청/응답의 출처. 클라이언트에서 시작되었으면 client, 서버에서 시작되었으면 server, 출처를 알 수 없으면 unknown으로 설정.

옵션

| 옵션 키 | 옵션 값 | 설명 | | exemplars | true | HTTP 메트릭에 추출된 trace ID 포함. OpenMetrics 활성화 필요 |

이 메트릭은 컨텍스트 옵션을 지원합니다.

`icmp`

| 이름 | 라벨 | 기본값 | 설명 | | icmp_total | family, type | Disabled | ICMP 메시지 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`port-distribution`

| 이름 | 라벨 | 기본값 | 설명 | | port_distribution_total | protocol, port | Disabled | 대상 포트별로 분산된 패킷 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`tcp`

| 이름 | 라벨 | 기본값 | 설명 | | tcp_flags_total | flag, family | Disabled | TCP 플래그 발생 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

`sctp`

| 이름 | 라벨 | 기본값 | 설명 | | sctp_chunk_types_total | chunk_type, family | Disabled | SCTP 청크 타입 발생 수 |

옵션

이 메트릭은 컨텍스트 옵션을 지원합니다.

dynamic_exporter_exporters_total

동적 hubble exporter 메트릭이에요.

| 이름 | 라벨 | 기본값 | 설명 | | dynamic_exporter_exporters_total | status | Enabled | 구성된 hubble exporter 수 |

라벨

status는 exporter 상태를 식별하며, 다음 중 하나:
- active
- inactive

dynamic_exporter_up

동적 hubble exporter 메트릭이에요.

| 이름 | 라벨 | 기본값 | 설명 | | dynamic_exporter_up | name | Enabled | exporter 상태 (1 - active, 0 - inactive) |

라벨

name은 exporter 이름을 식별.

dynamic_exporter_reconfigurations_total

동적 hubble exporter 메트릭이에요.

| 이름 | 라벨 | 기본값 | 설명 | | dynamic_exporter_reconfigurations_total | op | Enabled | 동적 exporter 재구성 횟수 |

라벨

op는 재구성 연산 유형을 식별하며, 다음 중 하나:
- add
- update
- remove

dynamic_exporter_config_hash

동적 hubble exporter 메트릭이에요.

| 이름 | 라벨 | 기본값 | 설명 | | dynamic_exporter_config_hash | | Enabled | 마지막으로 적용된 구성의 해시 |

dynamic_exporter_config_last_applied

동적 hubble exporter 메트릭이에요.

| 이름 | 라벨 | 기본값 | 설명 | | dynamic_exporter_config_last_applied | | Enabled | 마지막으로 적용된 구성의 타임스탬프 |

clustermesh-apiserver

구성 (Configuration)

메트릭을 노출하려면 clustermesh-apiserver를 --prometheus-serve-addr 옵션으로 실행하세요. 이 옵션은 IP:Port 쌍을 받지만 빈 IP(예: :9962)를 전달하면 서버가 모든 인터페이스에 바인딩됩니다(컨테이너에는 보통 하나만 있어요).

내보내기 메트릭 (Exported Metrics)

모든 메트릭은 cilium_clustermesh_apiserver_ Prometheus 네임스페이스 아래로 내보내집니다.

Bootstrap

| 이름 | 설명 | | bootstrap_seconds | bootstrap을 완료하는 데 걸린 시간(초) |

KVstore

API Rate Limiting

Controllers

| 이름 | 라벨 | 기본값 | 설명 | | controllers_group_runs_total | status, group_name | Enabled | 컨트롤러 그룹 이름으로 구분된 컨트롤러 프로세스 실행 횟수 |

controllers_group_runs_total 메트릭은 시스템 내 각 컨트롤러의 성공·실패 횟수를 컨트롤러 그룹 이름과 완료 상태로 구분해 보고해요. 이 메트릭은 컨트롤러별로 활성화됩니다. 이는 controller-group-metrics 구성 플래그로 전달되는 allow-list로 구성돼요. Cilium Helm 차트의 clustermesh-apiserver 기본 집합은 특별한 이름 "all"로, 모든 컨트롤러 그룹에 대해 메트릭을 활성화합니다. 특별한 이름 "none"도 지원됩니다.

kvstoremesh

구성 (Configuration)

메트릭을 노출하려면 kvstoremesh를 --prometheus-serve-addr 옵션으로 실행하세요. 이 옵션은 IP:Port 쌍을 받지만 빈 IP(예: :9964)를 전달하면 서버가 모든 인터페이스에 바인딩됩니다(컨테이너에는 보통 하나만 있어요).

내보내기 메트릭 (Exported Metrics)

모든 메트릭은 cilium_kvstoremesh_ Prometheus 네임스페이스 아래로 내보내집니다.

Bootstrap

| 이름 | 설명 | | bootstrap_seconds | bootstrap을 완료하는 데 걸린 시간(초) |

KVStoremesh

| 이름 | 라벨 | 설명 | | leader_election_master_status | name | 리더 선출 상태 |

Clustermesh

이 메트릭들은 clustermesh_ 접두사가 붙지 않는다는 점을 참고하세요.

KVstore

API Rate Limiting

Controllers

| 이름 | 라벨 | 기본값 | 설명 | | controllers_group_runs_total | status, group_name | Enabled | 컨트롤러 그룹 이름으로 구분된 컨트롤러 프로세스 실행 횟수 |

controllers_group_runs_total 메트릭은 시스템 내 각 컨트롤러의 성공·실패 횟수를 컨트롤러 그룹 이름과 완료 상태로 구분해 보고해요. 이 메트릭은 컨트롤러별로 활성화됩니다. 이는 controller-group-metrics 구성 플래그로 전달되는 allow-list로 구성돼요. Cilium Helm 차트의 kvstoremesh 기본 집합은 특별한 이름 "all"로, 모든 컨트롤러 그룹에 대해 메트릭을 활성화합니다. 특별한 이름 "none"도 지원됩니다.

NAT

| 이름 | 라벨 | 기본값 | 설명 | | nat_endpoint_max_connection | family | Enabled | egress-IP와 원격 엔드포인트 주소 기준으로 가장 포화된 고유 NAT 매핑 연결의 포화도. |

이 메트릭들은 Cilium의 NAT 매핑 기능을 모니터링하기 위한 것입니다. NAT는 Egress Gateway와 BPF masquerading 같은 기능에 사용돼요.

NAT 맵은 masquerade된 연결의 매핑을 보관합니다. 같은 egress-IP로 masquerade되고 같은 원격 엔드포인트 IP·포트로 향하는 NAT 테이블의 연결은 모두 매핑에 고유한 소스 포트가 필요해요. 즉, 별개의 외부 엔드포인트로 masquerade하는 노드는 가능한 임시(ephemeral) 소스 포트에 의해 제한됩니다.

노드가 하나 이상의 egress-IP·원격 엔드포인트 튜플을 포워딩할 때, nat_endpoint_max_connection 메트릭은 사용 가능한 소스 포트의 백분율 측면에서 가장 포화된 그러한 연결입니다. 이 메트릭은 많은 연결이 같은 엔드포인트로 갈 때 노드가 과부하될 수 있는 egress gateway 기능을 사용할 때 특히 유용해요. 일반적으로 이 메트릭은 보통 상당히 낮아야 합니다. 여기서 높은 값은 노드가 하나 이상의 외부 엔드포인트에 대한 연결 한계에 도달하고 있음을 나타낼 수 있어요.

Local Redirect Policy (control plane)

| 이름 | 라벨 | 기본값 | 설명 | | controller_duration_seconds | | Enabled | 로컬 리다이렉트 정책 처리 시간 히스토그램 |