Traefik 메트릭 개요

원문 보기 위키 갱신 2026.10.03

Traefik 메트릭 개요 (Traefik Metrics Overview)

출처: Traefik Metrics Overview

본문

메트릭 (Metrics)

Traefik은 OpenTelemetry 형식과 함께 다음 벤더 특정 백엔드로 메트릭을 제공해요:

Datadog
InfluxDB2
Prometheus
StatsD

Traefik Proxy는 온프레미스와 Kubernetes 배포 모두를 위한 공식 Grafana 대시보드가 있어요.

OpenTelemetry

기본 프로토콜 (Default protocol)

OpenTelemetry 익스포터는 기본적으로 HTTP를 사용해 https://localhost:4318로 컬렉터에 메트릭을 내보내요.

설정 예시 (Configuration Example)

OpenTelemetry 메트릭을 활성화하려면:

파일 (YAML)

metrics:
  otlp: {}

파일 (TOML)

[metrics]
  [metrics.otlp]

CLI

--metrics.otlp=true

Helm 차트 값 (Helm Chart Values)

# values.yaml
metrics:
  # Disable Prometheus (enabled by default)
  prometheus: null
  # Enable providing OTel metrics
  otlp:
    enabled: true
    http:
      enabled: true

Helm 차트 구성 (Helm Chart Configuration)

Helm Chart 값을 사용해 OpenTelemetry 형식으로 메트릭을 제공하도록 Traefik을 설정할 수 있어요. Helm Chart 옵션에 대한 자세한 내용은 Helm Chart를 참고하세요(옵션 metrics.otlp 찾기).

설정 옵션 (Configuration Options)

`metrics.otlp.http.headers` 익스포터가 메트릭과 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요.

| 아니오 (No) |

metrics.otlp.http.tls.ca OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. "" | 아니오 (No) |

metrics.otlp.http.tls.cert OpenTelemetry 컬렉터와의 보안 연결에 사용하는 공개 인증서의 경로예요. 이 옵션을 사용할 때는 key 옵션을 설정해야 합니다. "" | 아니오 (No) |

metrics.otlp.http.tls.key TLS 연결에 사용하는 개인 키의 경로를 정의해요. "" | 아니오 (No) |

metrics.otlp.http.tls.insecureskipverify OpenTelemetry 컬렉터와의 TLS 연결이 서버가 제시하는 인증서를 호스트 이름과 관계없이 수락할 수 있게 해 줘요. false | 예 (Yes) |

metrics.otlp.grpc 익스포터가 gRPC를 사용해 메트릭을 OpenTelemetry 컬렉터로 보내도록 지시해요. null/false | 아니오 (No) |

metrics.otlp.grpc.endpoint 메트릭을 보낼 OpenTelemetry 컬렉터의 주소예요. 형식=":" "localhost:4317" | 예 (Yes) |

`metrics.otlp.grpc.headers` 익스포터가 메트릭과 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요.

| 아니오 (No) |

metrics.otlp.grpc.insecure 익스포터가 보안 프로토콜 없이 메트릭을 OpenTelemetry 컬렉터로 보낼 수 있게 해 줘요. false | 예 (Yes) |

`metrics.otlp.grpc.tls.ca` OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요.

| 아니오 (No) |

`metrics.otlp.grpc.tls.cert` OpenTelemetry 컬렉터와의 보안 연결에 사용하는 공개 인증서의 경로예요. 이 옵션을 사용할 때는 `key` 옵션을 설정해야 합니다.

| 아니오 (No) |

`metrics.otlp.grpc.tls.key` TLS 연결에 사용하는 개인 키의 경로를 정의해요.

| 아니오 (No) |

metrics.otlp.grpc.tls.insecureskipverify OpenTelemetry 컬렉터와의 TLS 연결이 서버가 제시하는 인증서를 호스트 이름과 관계없이 수락할 수 있게 해 줘요. false | 예 (Yes) |

resourceAttributes

resourceAttributes 옵션은 트레이스와 함께 보내는 리소스 속성을 설정하게 해 줘요. Traefik은 리소스 속성을 설정하기 위해 OTEL_RESOURCE_ATTRIBUTES 환경 변수도 지원해요.

Kubernetes 리소스 속성 감지 (Kubernetes Resource Attributes Detection)

추가로 Traefik은 Kubernetes 클러스터에서 실행될 때 다음 Kubernetes 리소스 속성을 자동으로 발견해요:

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

이 자동 감지는 예를 들어 Traefik 파드가 호스트 네트워크 모드로 실행되는 경우처럼 실패할 수 있다는 점을 주의하세요. 그런 경우 옵션이나 환경 변수로 속성을 직접 제공해야 해요.

벤더 (Vendors)

Datadog

설정 예시 (Configuration Example)

Datadog을 활성화하려면:

파일 (YAML)

metrics:
  datadog: {}

파일 (TOML)

[metrics]
  [metrics.datadog]

CLI

--metrics.datadog=true

설정 옵션 (Configuration Options)

address Address는 익스포터가 이 주소의 datadog-agent로 메트릭을 보내도록 지시해요.

이 주소는 unix:///path/to/datadog.socket 형식의 Unix 도메인 소켓(UDS)일 수 있어요. 접두사가 unix로 설정되면 소켓 유형이 자동 결정돼요. 소켓 유형을 명시적으로 정의하고 자동 감지를 피하려면, SOCK_DGRAM(데이터그램 소켓)에는 unixgram, SOCK_STREAM(스트림 소켓)에는 unixstream 접두사를 각각 사용할 수 있어요.

파일 (YAML)

metrics:
  datadog:
    address: localhost:8125

파일 (TOML)

[metrics]
  [metrics.datadog]
    address = "localhost:8125"

CLI

--metrics.datadog.address=localhost:8125

InfluxDB v2

설정 예시 (Configuration Example)

InfluxDB2를 활성화하려면:

파일 (YAML)

metrics:
  influxDB2:
    address: http://localhost:8086

파일 (TOML)

[metrics]
  [metrics.influxDB2]
    address: http://localhost:8086

CLI

--metrics.influxdb2=true

설정 옵션 (Configuration Options)

Prometheus

설정 예시 (Configuration Example)

Prometheus를 활성화하려면:

파일 (YAML)

metrics:
  prometheus:
    buckets:
      - 0.1
      - 0.3
      - 1.2
      - 5.0

파일 (TOML)

[metrics]
  [metrics.prometheus]
    [metrics.prometheus.buckets]
      - 0.1
      - 0.3
      - 1.2
      - 5.0

CLI

--metrics.prometheus=true

설정 옵션 (Configuration Options)

headerLabels requests_total 메트릭의 추가 라벨과, 각 라벨에 대해 그 라벨의 값을 담은 요청 헤더를 정의해요. 헤더가 요청에 없으면, 빈 값으로 추가되기는 해요. 라벨은 Prometheus 메트릭에 유효한 라벨 이름이어야 해요. 그렇지 않으면 Prometheus 메트릭 프로바이더가 Traefik 관련 메트릭을 전혀 제공하지 못해요.

Host 헤더 값을 제공하는 방법 (How to provide the Host header value)

Host 헤더는 Go 문서가 말하듯 요청의 Header 맵에 결코 존재하지 않아요:

// For incoming requests, the Host header is promoted to the
// Request.Host field and removed from the Header map.

해결 방법으로, 요청의 Host를 라벨로 얻으려면 대신 X-Forwarded-Host 헤더를 사용하세요.

설정 예시 (Configuration Example) 추가 "useragent" 라벨이 있는 entryPoint requests_total 메트릭의 예시예요.

정적 설정(Static Configuration)에서 라벨을 구성할 때:

설정 (Configuration)

# static_configuration.yaml
metrics:
  prometheus:
    headerLabels:
      useragent: User-Agent

요청 (Request)

curl -H "User-Agent: foobar" http://localhost

메트릭 (Metric)

traefik_entrypoint_requests_total\{code="200",entrypoint="web",method="GET",protocol="http",useragent="foobar"\} 1

StatsD

설정 예시 (Configuration Example)

Statsd를 활성화하려면:

파일 (YAML)

metrics:
  statsD:
    address: localhost:8125

파일 (TOML)

[metrics]
  [metrics.statsD]
    address: localhost:8125

CLI

--metrics.statsd=true

설정 옵션 (Configuration Options)

제공되는 메트릭 (Metrics Provided)

전역 메트릭 (Global Metrics)

StatsD | 메트릭 (Metric) | 타입 (Type) | 라벨 (Labels) | 설명 (Description) | | {prefix}.config.reload.total | Count | | 설정 리로드의 총 횟수예요. | | {prefix}.config.reload.lastSuccessTimestamp | Gauge | | 마지막 설정 리로드 성공 시점의 타임스탬프예요. | | {prefix}.open.connections | Gauge | entrypoint, protocol | 엔트리포인트·프로토콜별 현재 열린 연결 수예요. | | {prefix}.tls.certs.notAfterTimestamp | Gauge | | 인증서의 만료 날짜예요. |

{prefix} 기본값 (Default Value)기본적으로 {prefix} 값은 traefik이에요.

라벨 (Labels)

전역 메트릭이 제공하는 라벨의 포괄적인 목록은 다음과 같아요:

OpenTelemetry 시맨틱 규칙 (OpenTelemetry Semantic Conventions)

Traefik Proxy는 공식 OpenTelemetry 시맨틱 규칙 v1.23.1을 따릅니다.

HTTP 서버 (HTTP Server)

라벨 (Labels) 메트릭이 제공하는 라벨의 포괄적인 목록은 다음과 같아요:

HTTP 클라이언트 (HTTP Client)

라벨 (Labels) 메트릭이 제공하는 라벨의 포괄적인 목록은 다음과 같아요:

HTTP 메트릭 (HTTP Metrics)

공식 OpenTelemetry 시맨틱 규칙에 더해, Traefik은 들어오는 트래픽을 모니터링하기 위한 자체 메트릭을 제공해요.

엔트리포인트 메트릭 (EntryPoint Metrics)

StatsD | 메트릭 (Metric) | 타입 (Type) | 라벨 (Labels) | 설명 (Description) | | {prefix}.entrypoint.requests.total | Count | code, method, protocol, entrypoint | 엔트리포인트가 받은 HTTP 요청의 총 횟수예요. | | {prefix}.entrypoint.requests.tls.total | Count | tls_version, tls_cipher, entrypoint | 엔트리포인트가 받은 HTTPS 요청의 총 횟수예요. | | {prefix}.entrypoint.request.duration.seconds | Histogram | code, method, protocol, entrypoint | 엔트리포인트의 요청 처리 기간 히스토그램이에요. | | {prefix}.entrypoint.requests.bytes.total | Count | code, method, protocol, entrypoint | 엔트리포인트가 처리한 HTTP 요청의 총 크기(바이트)예요. | | {prefix}.entrypoint.responses.bytes.total | Count | code, method, protocol, entrypoint | 엔트리포인트가 처리한 HTTP 응답의 총 크기(바이트)예요. |

{prefix} 기본값 (Default Value)기본적으로 {prefix} 값은 traefik이에요.

라우터 메트릭 (Router Metrics)

StatsD | 메트릭 (Metric) | 타입 (Type) | 라벨 (Labels) | 설명 (Description) | | {prefix}.router.requests.total | Count | code, method, protocol, router, service | 라우터가 처리한 HTTP 요청의 총 횟수예요. | | {prefix}.router.requests.tls.total | Count | tls_version, tls_cipher, router, service | 라우터가 처리한 HTTPS 요청의 총 횟수예요. | | {prefix}.router.request.duration.seconds | Histogram | code, method, protocol, router, service | 라우터의 요청 처리 기간 히스토그램이에요. | | {prefix}.router.requests.bytes.total | Count | code, method, protocol, router, service | 라우터가 처리한 HTTP 요청의 총 크기(바이트)예요. | | {prefix}.router.responses.bytes.total | Count | code, method, protocol, router, service | 라우터가 처리한 HTTP 응답의 총 크기(바이트)예요. |

{prefix} 기본값 (Default Value)기본적으로 {prefix} 값은 traefik이에요.

서비스 메트릭 (Service Metrics)

StatsD | 메트릭 (Metric) | 타입 (Type) | 라벨 (Labels) | 설명 (Description) | | {prefix}.service.requests.total | Count | code, method, protocol, service | 서비스에서 처리한 HTTP 요청의 총 횟수예요. | | {prefix}.service.requests.tls.total | Count | tls_version, tls_cipher, service | 서비스에서 처리한 HTTPS 요청의 총 횟수예요. | | {prefix}.service.request.duration.seconds | Histogram | code, method, protocol, service | 서비스의 요청 처리 기간 히스토그램이에요. | | {prefix}.service.retries.total | Count | service | 서비스에서 요청이 재시도된 횟수예요. | | {prefix}.service.server.up | Gauge | service, url | 현재 서비스의 서버 상태로, 다운이면 0, 업이면 1이에요. 헬스체크로 구성된 서비스에만 해당돼요. | | {prefix}.service.requests.bytes.total | Count | code, method, protocol, service | 서비스가 받은 요청의 총 크기(바이트)예요. | | {prefix}.service.responses.bytes.total | Count | code, method, protocol, service | 서비스가 반환한 응답의 총 크기(바이트)예요. |

{prefix} 기본값 (Default Value)기본적으로 {prefix} 값은 traefik이에요.

라벨 (Labels) 메트릭이 제공하는 라벨의 포괄적인 목록은 다음과 같아요:

method 라벨 값

요청의 HTTP 메서드 동사가 HTTP/1.1 일반 메서드 집합에 정의된 것이 아니거나(HTTP/2의) PRI 동사가 아니면, method 라벨의 값은 EXTENSION_METHOD이 돼요.

더 알아보기 (Learn more)

Traefik 공식 문서

Traefik 메트릭 개요