Proxy Metrics

Proxy Metrics (프록시 메트릭)

Linkerd 프록시가 Prometheus 형식으로 내보내는 각종 메트릭(프로세스, 프로토콜, 전송, 신원, 엔드포인트)과 레이블을 설명하는 문서예요.

출처: Linkerd Proxy Metrics

본문

Linkerd 프록시는 프록시를 통과하는 트래픽을 설명하는 메트릭을 노출합니다. 다음 메트릭들은 프록시의 metrics 포트(기본값 :4191)의 /metrics에서 Prometheus 형식으로 제공됩니다.

프로세스 수준 메트릭 (Process-Level Metrics)

• proxy_build_info: 이 프록시 인스턴스가 어떻게 빌드되었는지(빌드 날짜, 프록시 버전 등)에 대한 상수 gauge.
• rustls_info: 프록시의 TLS 라이브러리인 rustls에 대한 정보를 담은 상수 gauge. 다음 레이블을 포함합니다:
  • tls_suites: 프록시가 TLS 연결에 사용할 cipher suite 집합. 선호 순서대로 정렬됨.
  • tls_kx_groups: 프록시가 사용할 키 교환 알고리즘 집합. 선호 순서대로 정렬됨.
  • tls_rand: 보안 난수 공급자
  • tls_key_provider: 암호화 키 공급자
  • tls_fips: 프록시의 연결이 FIPS를 준수하는지 나타내는 boolean.
• tokio_rt_*: 프록시의 비동기 런타임인 tokio에 대한 통계를 담은 카운터와 gauge 집합.

프로토콜 수준 메트릭 (Protocol-Level Metrics)

• request_total: 프록시가 수신한 요청 수를 세는 카운터. 요청 스트림이 시작될 때 증가합니다.
• response_total: 프록시가 수신한 응답 수를 세는 카운터. 응답 스트림이 끝날 때 증가합니다.
• response_latency_ms: 응답 지연 시간의 히스토그램. 이 측정은 프록시가 요청 헤더를 처리한 시점부터 응답의 첫 데이터 프레임까지의 경과 시간을 기록함으로써 첫 바이트까지의 시간(TTFB, time-to-first-byte)을 반영합니다. 응답에 데이터가 없으면 end-of-stream 이벤트가 사용됩니다. TTFB 측정을 사용하는 이유는, 서버가 응답 헤더는 즉시 제공하지만 응답 본문 서빙은 느리게 시작하는 경우에 Linkerd가 애플리케이션 동작을 정확히 반영하도록 하기 위함입니다.
• route_request_total, route_response_latency_ms, route_response_total: 이 메트릭들은 request_total, response_latency_ms, response_total과 유사하지만, 라우트 수준에서 수집됩니다. 즉 authority, tls, grpc_status_code나 모든 outbound 레이블이 없고 대신 다음을 가집니다:
  • dst: 이 요청의 authority.
  • rt_route: 이 요청의 라우트 이름.
• control_request_total, control_response_latency_ms, control_response_total: 이 메트릭들은 request_total, response_latency_ms, response_total과 유사하지만 프록시가 Linkerd 컨트롤 플레인으로 보내는 요청에 대한 것입니다. authority, direction, outbound 레이블 대신 다음을 가집니다:
  • addr: 컨트롤 플레인에 연결할 때 사용된 주소.
• inbound_http_authz_allow_total: 인가된 인바운드 HTTP 요청의 총 수를 세는 카운터.
  • authz_name: 요청을 허용하는 데 사용된 인가 정책의 이름.
• inbound_http_authz_deny_total: 인가 정책에 의해 거부되어 처리되지 못한 인바운드 HTTP 요청의 총 수를 세는 카운터.
• inbound_http_route_not_found_total: 어떤 라우트와도 연관 지을 수 없었던 인바운드 HTTP 요청의 총 수를 세는 카운터.

지연 시간 측정값은 스트림이 완료될 때까지 Prometheus로 내보내지지 않는다는 점을 주의하세요. 지연 시간을 적절한 응답 분류로 레이블링할 수 있도록 하기 위해 필요합니다.

레이블 (Labels)

다음 각 메트릭은 다음 레이블을 가집니다:

• authority: 요청의 :authority (HTTP/2) 또는 Host (HTTP/1.1) 헤더 값.
• direction: 요청이 파드 외부에서 시작되었으면 inbound, 파드 내부에서 시작되었으면 outbound.
• tls: 요청의 연결이 TLS로 보호되었으면 true.

Authority 레이블

direction=inbound 레이블 값을 가진 메트릭에서는 authority 레이블이 생략됩니다. 이는 악의적인 클라이언트가 임의의 다양한 authority 값을 가진 요청을 보내 Linkerd가 무한히 많은 메트릭을 만들지 못하게 하는 보안 조치로 수행됩니다.

이것이 환경에서 우려되지 않는다면, Linkerd의 values.yml에 추가 env 값을 설정해 이 메트릭들에서 authority 레이블을 다시 활성화할 수 있습니다:

`proxy:
  additionalEnv:
    - name: LINKERD2_PROXY_INBOUND_METRICS_AUTHORITY_LABELS
      value: unsafe
`

응답 레이블 (Response Labels)

다음 레이블은 response_* 메트릭에만 적용됩니다.

• status_code: 응답의 HTTP 상태 코드.

Response Total 레이블

모든 response_* 메트릭에 적용되는 레이블에 더해, response_total, route_response_total, control_response_total 메트릭은 다음 레이블도 가집니다:

• classification: 응답이 성공이면 success, 서버 오류가 발생했으면 failure. 이 분류는 gRPC 상태 코드가 있으면 그것에, 없으면 HTTP 상태 코드에 기반합니다.
• grpc_status_code: grpc-status 트레일러 값. gRPC 응답에만 적용됩니다.

Note

응답 분류는 grpc-status 트레일러(있는 경우)에 기반해 결정될 수 있으므로, 응답은 본문 스트림이 완료될 때까지 분류되지 않을 수 있어요. 하지만 응답 지연 시간은 첫 바이트까지의 시간에 기반하므로 response_latency_ms 메트릭은 응답 본문이 끝날 때가 아니라 데이터가 수신되는 즉시 기록됩니다. 따라서 response_latency_ms 메트릭이 기록될 때 classification과 grpc_status_code 레이블의 값은 아직 알려지지 않습니다.

Outbound 레이블

다음 레이블은 direction=outbound일 때만 적용됩니다.

• dst_deployment: 이 요청이 전송되는 deployment.
• dst_k8s_job: 이 요청이 전송되는 job.
• dst_replicaset: 이 요청이 전송되는 replica set.
• dst_daemonset: 이 요청이 전송되는 daemon set.
• dst_statefulset: 이 요청이 전송되는 stateful set.
• dst_replicationcontroller: 이 요청이 전송되는 replication controller.
• dst_namespace: 이 요청이 전송되는 네임스페이스.
• dst_service: 이 요청이 전송되는 서비스.
• dst_pod_template_hash: 이 요청이 전송되는 파드의 pod-template-hash. 이 레이블 선택자는 대략 파드의 ReplicaSet 또는 ReplicationController에 해당합니다.

Prometheus Collector 레이블

다음 레이블은 Prometheus collector가 추가합니다.

• instance: 파드의 ip:port.
• job: 수집을 담당하는 Prometheus job, 보통 linkerd-proxy.

수집 시점에 추가되는 Kubernetes 레이블 (Kubernetes labels added at collection time)

Kubernetes 네임스페이스, 파드 이름, 모든 레이블은 해당 Prometheus 레이블로 매핑됩니다.

• namespace: 파드가 속한 Kubernetes 네임스페이스.
• pod: Kubernetes 파드 이름.
• pod_template_hash: pod-template-hash Kubernetes 레이블에 해당. 이 값은 재배포(redeploy)와 롤링 재시작 중에 변경됩니다. 이 레이블 선택자는 대략 파드의 ReplicaSet 또는 ReplicationController에 해당합니다.

수집 시점에 추가되는 Linkerd 레이블 (Linkerd labels added at collection time)

linkerd.io/ 접두사가 붙은 Kubernetes 레이블은 linkerd inject 시점에 애플리케이션에 추가됩니다. 더 구체적으로, linkerd.io/proxy-* 접두사가 붙은 Kubernetes 레이블은 다음 Prometheus 레이블에 해당합니다:

• daemonset: 파드가 속한 daemon set (해당하는 경우).
• deployment: 파드가 속한 deployment (해당하는 경우).
• k8s_job: 파드가 속한 job (해당하는 경우).
• replicaset: 파드가 속한 replica set (해당하는 경우).
• replicationcontroller: 파드가 속한 replication controller (해당하는 경우).
• statefulset: 파드가 속한 stateful set (해당하는 경우).

예제 (Example)

다음 파드 스니펫을 사용한 구체적인 예를 들어볼게요:

`name: vote-bot-5b7f5657f6-xbjjw
namespace: emojivoto
labels:
  app: vote-bot
  linkerd.io/control-plane-ns: linkerd
  linkerd.io/proxy-deployment: vote-bot
  pod-template-hash: "3957278789"
  test: vote-bot-test
`

결과 Prometheus 레이블은 이렇게 보입니다:

`request_total{
  pod="vote-bot-5b7f5657f6-xbjjw",
  namespace="emojivoto",
  app="vote-bot",
  control_plane_ns="linkerd",
  deployment="vote-bot",
  pod_template_hash="3957278789",
  test="vote-bot-test",
  instance="10.1.3.93:4191",
  job="linkerd-proxy"
}
`

전송 수준 메트릭 (Transport-Level Metrics)

다음 메트릭들은 기반 전송 계층 수준에서 수집됩니다.

• tcp_open_total: 열린 전송 연결의 총 수를 세는 카운터.
• tcp_close_total: 닫힌 전송 연결의 총 수를 세는 카운터.
• tcp_open_connections: 현재 열려 있는 전송 연결 수의 gauge.
• tcp_write_bytes_total: 보낸 총 바이트 수를 세는 카운터. 연결이 닫힐 때 갱신됩니다.
• tcp_read_bytes_total: 받은 총 바이트 수를 세는 카운터. 연결이 닫힐 때 갱신됩니다.
• inbound_tcp_errors_total: 프록시 오류로 처리하지 못한 인바운드 TCP 연결의 총 수를 세는 카운터.
• outbound_tcp_errors_total: 프록시 오류로 처리하지 못한 아웃바운드 TCP 연결의 총 수를 세는 카운터.
• inbound_tcp_authz_allow_total: 인가된 TCP 연결의 총 수를 세는 카운터.
• inbound_tcp_authz_deny_total: 거부된 TCP 연결의 총 수를 세는 카운터.

레이블 (Labels)

다음 각 메트릭은 다음 레이블을 가집니다:

• direction: 연결이 파드 외부에서 프록시로 또는 프록시에서 애플리케이션으로 설정되었으면 inbound, 애플리케이션에서 프록시로 또는 프록시에서 파드 외부로 설정되었으면 outbound.
• peer: 연결이 소스에서 프록시에 의해 수락되었으면 src, 연결이 프록시에 의해 목적지로 열렸으면 dst.

위에서 "Prometheus Collector 레이블" 제목 아래 설명한 레이블도 해당하는 경우 전송 수준 메트릭에 추가된다는 점을 참고하세요.

연결 종료 레이블 (Connection Close Labels)

다음 레이블은 연결이 닫힐 때 갱신되는 메트릭(tcp_close_total)에만 추가됩니다:

• classification: 연결이 깨끗하게 종료되었으면 success, 연결 실패로 닫혔으면 failure.

신원 메트릭 (Identity Metrics)

• identity_cert_expiration_timestamp_seconds: 프록시의 현재 mTLS 신원 인증서가 만료되는 시각(UNIX epoch 이후 초)의 gauge.
• identity_cert_refresh_count: Identity 서비스가 프록시의 mTLS 신원 인증서를 갱신한 총 횟수를 세는 카운터.

엔드포인트 메트릭 (Endpoint Metrics)

정책 기반 라우팅을 수행할 때 프록시는 라우트별 백엔드 구성을 통해 요청을 배포할 수 있어요. 정책 기반 라우팅 구성 방법에 대한 자세한 내용은 Authorization Policy 개요와 reference 문서를 참고하세요.

Linkerd 프록시는 인가된 HTTP 및 gRPC 트래픽에 대한 가시성을 제공하는 메트릭을 내보냅니다. 라우트 수준 메트릭은 정책의 모든 관련 백엔드에 대한 트래픽을 측정하고, 백엔드 수준 메트릭은 개별 엔드포인트에 분산된 트래픽을 측정합니다.

아웃바운드 프록시는 다음 메트릭을 기록합니다:

• outbound_http_route_request_duration_seconds: HTTP 요청 초기화와 HTTP 응답 완료 사이의 시간을 측정하는 히스토그램.
• outbound_http_route_request_statuses_total: 라우트로 보낸 HTTP 트래픽의 HTTP 응답 상태 코드를 추적하는 카운터.
• outbound_http_route_request_frame_size_bytes: 라우트의 HTTP 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• outbound_grpc_route_request_duration_seconds: gRPC 요청 초기화와 gRPC 응답 완료 사이의 시간을 측정하는 히스토그램.
• outbound_grpc_route_request_statuses_total: GRPCRoute로 보낸 gRPC 트래픽의 gRPC 응답 상태 코드를 추적하는 카운터.
• outbound_grpc_route_request_frame_size_bytes: 라우트의 gRPC 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• outbound_http_route_backend_requests_total: 특정 백엔드로 배포된 아웃바운드 HTTP 요청의 총 수를 추적하는 카운터.
• outbound_http_route_backend_response_duration_seconds: 특정 백엔드에 대해 HTTP 요청 완료와 HTTP 응답 완료 사이의 시간(초)을 측정하는 히스토그램.
• outbound_http_route_backend_response_statuses_total: 상태 코드로 레이블링된, 특정 백엔드의 HTTP 응답을 추적하는 카운터.
• outbound_http_route_backend_response_frame_size_bytes: 특정 백엔드의 HTTP 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• outbound_grpc_route_backend_requests_total: 특정 백엔드로 배포된 아웃바운드 gRPC 요청의 총 수를 추적하는 카운터.
• outbound_grpc_route_backend_response_duration_seconds: 특정 백엔드로 배포된 트래픽에 대해 gRPC 요청 완료와 gRPC 응답 완료 사이의 시간(초)을 측정하는 히스토그램.
• outbound_grpc_route_backend_response_statuses_total: grpc-status 코드로 레이블링된, 특정 백엔드의 gRPC 응답을 추적하는 카운터.
• outbound_grpc_route_backend_response_frame_size_bytes: 특정 백엔드의 gRPC 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.

인바운드 프록시는 다음 메트릭을 기록합니다:

• inbound_http_requests_total: 특정 백엔드가 수신한 인바운드 HTTP 요청의 총 수를 추적하는 카운터.
• inbound_grpc_requests_total: 특정 백엔드가 수신한 인바운드 gRPC 요청의 총 수를 추적하는 카운터.
• inbound_http_statuses_total: 특정 백엔드가 수신한 HTTP 트래픽의 HTTP 응답 상태 코드를 추적하는 카운터.
• inbound_grpc_statuses_total: 특정 백엔드가 수신한 gRPC 트래픽의 gRPC 응답 상태 코드를 추적하는 카운터.
• inbound_http_request_duration_seconds: HTTP 요청 초기화와 HTTP 응답 완료 사이의 시간을 측정하는 히스토그램.
• inbound_http_response_duration_seconds: 특정 백엔드에 대해 HTTP 요청 완료와 HTTP 응답 완료 사이의 시간(초)을 측정하는 히스토그램.
• inbound_grpc_request_duration_seconds: gRPC 요청 초기화와 gRPC 응답 완료 사이의 시간을 측정하는 히스토그램.
• inbound_grpc_response_duration_seconds: 특정 백엔드에 대해 gRPC 요청 완료와 gRPC 응답 완료 사이의 시간(초)을 측정하는 히스토그램.
• inbound_http_request_frame_size_bytes: 특정 라우트의 HTTP 요청 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• inbound_http_response_frame_size_bytes: 특정 라우트의 HTTP 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• inbound_grpc_request_frame_size_bytes: 특정 라우트의 gRPC 요청 본문에서 DATA 프레임 크기를 측정하는 히스토그램.
• inbound_grpc_response_frame_size_bytes: 특정 라우트의 gRPC 응답 본문에서 DATA 프레임 크기를 측정하는 히스토그램.

레이블 (Labels)

다음 각 메트릭은 프록시가 트래픽을 라우팅하는 Kubernetes 리소스를 설명하는 다음 공통 레이블을 가집니다:

• parent_group, parent_kind, parent_name, parent_namespace: 프록시가 라우트 바인딩을 발견한 상위(parent) 리소스를 참조. HTTPRoute의 상위 리소스는 일반적으로 Service입니다.
• route_group, route_kind, route_name, route_namespace: 프록시가 라우트 바인딩을 발견한 라우트 리소스를 참조. 이는 HTTPRoute 리소스 또는 기본(합성) 라우트를 참조합니다.
• backend_group, backend_kind, backend_name, backend_namespace: 프록시가 요청을 라우팅한 백엔드 리소스를 참조. 이는 항상 Service입니다.

또한 outbound_http_balancer_endpoints gauge 메트릭은 다음 레이블을 추가합니다:

• endpoint_state: 엔드포인트가 로드 밸런서가 요청을 라우팅하기에 사용 가능하면 "ready", 현재 사용 불가능하면 "pending". 엔드포인트는 연결이 (재)설정되는 중이거나, failure accrual에 의해 사용 불가능해졌을 때 "pending" 상태일 수 있습니다.

메트릭 만료 (Metric Expiry)

Linkerd 프록시는 높은 카디널리티 레이블을 가진 일부 메트릭을 내보냅니다. 예를 들어 메시에 포함된 노드가 많은 클러스터는 같은 레이블에 대해 많은 IP 주소를 가질 수 있어요. 장기 실행 프록시에서는 메모리 사용량이 늘어나므로 문제가 될 수 있습니다.

Linkerd 프록시는 매번 Prometheus 스크레이프 때마다 "사용되지 않는(unused)" 또는 "유휴(idle)" 메트릭을 폐기함으로써 높은 카디널리티 메트릭 수를 제한하려고 합니다. 메트릭이 프록시 내 어떤 컴포넌트도 참조하지 않으면 "unused"로 간주됩니다. 예를 들어 TCP 연결이 종료되고 그 TCP 연결 관련 메트릭이 더 이상 참조되지 않는 경우입니다. 메트릭이 미리 정의된 기간 내에 갱신되지 않았으면 "idle"로 간주됩니다. 기본 기간은 10분이며, LINKERD2_PROXY_METRICS_RETAIN_IDLE를 구성해 기본값을 설정할 수 있습니다.

메트릭 만료는 프록시 내 다음 메트릭에 적용됩니다:

• request_total
• response_total
• response_latency_ms
• route_request_total
• route_response_total
• route_response_latency_ms
• route_actual_request_total
• route_actual_response_total
• route_retryable_total
• control_request_total
• control_response_total
• control_response_latency_ms
• tcp_open_total
• tcp_open_connections
• tcp_read_bytes_total
• tcp_write_bytes_total
• tcp_close_total

더 알아보기 (Learn more)

• Linkerd 인가 정책(Authorization Policy) 개요와 reference 문서