메트릭 내보내기

원문 보기 위키 갱신 2026.10.03

Linkerd는 데이터 플레인을 통과하는 모든 트래픽에 대해 방대한 메트릭 세트를 제공해요. 이 메트릭은 프록시 레벨에서 수집되어 프록시의 메트릭 엔드포인트에 보고돼요.

일반적으로 이 메트릭을 소비하는 것은 프록시에서 직접 이뤄지지 않아요. 각 프록시는 전체 그림의 일부만 제공하기 때문이에요. 대신 별도의 도구를 사용해 모든 프록시에서 메트릭을 수집하고 함께 집계해 소비해요.

출처: Linkerd Exporting Metrics

본문

Linkerd 운영 팁

이 페이지에는 오픈 소스 커뮤니티가 최선의 노력(best-effort)으로 작성한 설명이 포함되어 있어요. 미션 크리티컬 애플리케이션을 운영하는 사용자는 Linkerd 프로덕션 리소스를 숙지하거나 상용 Linkerd 제공업체와 연결해야 해요.

쉬운 방법 중 하나는 linkerd-viz 확장이에요. 이 확장은 클러스터 내 Prometheus 인스턴스와 함께, 이를 활용하는 대시보드와 CLI 명령을 만들어줘요. 하지만 이 확장은 짧은 시간(6시간) 동안만 메트릭 데이터를 보관하며 재시작 시 데이터를 유지하지 않아요. 사용 사례에 따라 이 메트릭을 외부 메트릭 저장소로 내보내고 싶을 수 있어요.

이 메트릭을 클러스터 밖의 대상으로 내보내는 방법에는 여러 가지가 있어요:

linkerd-viz에서 자신의 Prometheus 클러스터로 데이터를 페더레이션(Federate)
linkerd-viz와 함께 Prometheus 통합 사용
Prometheus API를 통해 linkerd-viz에서 데이터 추출
linkerd-viz 없이 프록시에서 직접 데이터 수집

Prometheus federation API 사용

이미 Prometheus를 자신의 메트릭 저장소로 사용하고 있다면, Prometheus의 federation API를 활용하는 것을 추천해요. 이 API는 정확히 한 Prometheus에서 다른 Prometheus로 데이터를 복사하는 use case를 위해 설계된 것이에요.

Prometheus 설정 파일의 scrape_configs에 다음 항목을 추가하면 돼요 ({{.Namespace}}를 Linkerd Viz 확장이 실행 중인 네임스페이스로 바꾸세요):

- job_name: 'linkerd'
  kubernetes_sd_configs:
    - role: pod
      namespaces:
        names: ['{{.Namespace}}']

  relabel_configs:
    - source_labels:
        - __meta_kubernetes_pod_container_name
      action: keep
      regex: ^prometheus$

  honor_labels: true
  metrics_path: '/federate'

  params:
    'match[]':
      - '{job="linkerd-proxy"}'
      - '{job="linkerd-controller"}'

Prometheus를 구성하기 위해 Prometheus의 ServiceMonitors를 선호한다면, 이 ServiceMonitor YAML을 사용할 수 있어요 ({{.Namespace}}를 Linkerd Viz 확장이 실행 중인 네임스페이스로 바꾸세요):

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    k8s-app: linkerd-prometheus
    release: monitoring
  name: linkerd-federate
  namespace: {{.Namespace}}
spec:
  endpoints:
    - interval: 30s
      scrapeTimeout: 30s
      params:
        match[]:
          - '{job="linkerd-proxy"}'
          - '{job="linkerd-controller"}'
      path: /federate
      port: admin-http
      honorLabels: true
      relabelings:
        - action: keep
          regex: '^prometheus$'
          sourceLabels:
            - '__meta_kubernetes_pod_container_name'
  jobLabel: app
  namespaceSelector:
    matchNames:
      - {{.Namespace}}
  selector:
    matchLabels:
      component: prometheus

이제 끝이에요! 여러분의 Prometheus 클러스터가 Linkerd의 내부 Prometheus 인스턴스에서 Linkerd 메트릭을 페더레이션하도록 구성됐어요.

메트릭이 Prometheus에 들어오면, Linkerd 프록시 메트릭은 job="linkerd-proxy" 라벨을 갖고, Linkerd 컨트롤 플레인 메트릭은 job="linkerd-controller" 라벨을 가져요. 특정 메트릭과 라벨 정의에 대한 자세한 내용은 Proxy Metrics를 확인하세요.

Prometheus의 /federate 엔드포인트에 대한 자세한 내용은 Prometheus federation 문서를 확인하세요.

Prometheus 통합 사용

Prometheus를 자신의 장기 저장소로 사용하지 않는다면, Prometheus의 여러 통합 중 하나를 활용해 Linkerd의 Prometheus 인스턴스에서 원하는 데이터 저장소로 데이터를 자동으로 추출할 수 있어요. 자세한 내용은 Prometheus 문서를 참조하세요.

Prometheus API를 통한 데이터 추출

Prometheus federation도 Prometheus 통합도 사용할 수 없다면, Prometheus API를 호출해 Linkerd에서 데이터를 추출할 수 있어요.

예를 들어 다음과 같은 명령으로 federation API를 직접 호출할 수 있어요:

curl -G \
  --data-urlencode 'match[]={job="linkerd-proxy"}' \
  --data-urlencode 'match[]={job="linkerd-controller"}' \
  http://prometheus.linkerd-viz.svc.cluster.local:9090/federate

참고

데이터 저장소가 Kubernetes 클러스터 밖에 있다면, 원하는 도메인 이름에 인증을 갖춘ingress를 설정하고 싶을 거예요.

/federate API와 유사하게, Prometheus는 모든 메트릭을 가져오는 JSON 쿼리 API를 제공해요:

curl http://prometheus.linkerd-viz.svc.cluster.local:9090/api/v1/query?query=request_total

Linkerd 프록시에서 데이터 직접 수집

마지막으로, Linkerd의 Prometheus를 완전히 피하고 싶다면 Linkerd 프록시의 /metrics 엔드포인트를 직접 조회할 수 있어요.

예를 들어 linkerd 네임스페이스에서 실행 중인 단일 Linkerd 프록시의 /metrics를 보려면:

kubectl -n linkerd port-forward \
  $(kubectl -n linkerd get pods \
    -l linkerd.io/control-plane-ns=linkerd \
    -o jsonpath='{.items[0].metadata.name}') \
  4191:4191

그 다음에:

curl localhost:4191/metrics

또는 linkerd diagnostics proxy-metrics를 사용해 주어진 워크로드의 프록시 메트릭을 가져올 수도 있어요.