Traefik 추적 개요
Traefik 추적 개요 (Traefik Tracing Overview)
본문
추적 (Tracing)
요청 흐름 시각화하기 (Visualize the Requests Flow)
추적 시스템은 개발자가 인프라 안의 호출 흐름을 시각화할 수 있게 해 줘요.
Traefik은 분산 추적을 위해 설계된 오픈 표준인 OpenTelemetry를 사용해요.
설정 예시 (Configuration Example)
추적을 활성화하려면:
파일 (YAML)
tracing: {}
파일 (TOML)
[tracing]
CLI
--tracing=true
Helm 차트 값 (Helm Chart Values)
tracing:
otlp:
enabled: true
설정 옵션 (Configuration Options)
| 필드 (Field) | 설명 (Description) | 기본값 (Default) | 필수 (Required) |
| tracing.addInternals | 내부 리소스(예: ping@internal)에 대한 추적을 활성화해요. | false | 아니오 (No) |
| tracing.serviceName | 서비스 이름 리소스 속성을 정의해요. | "traefik" | 아니오 (No) |
| tracing.resourceAttributes | 컬렉터로 보낼 추가 리소스 속성을 정의해요. 자세한 내용은 resourceAttributes를 참고하세요. | {} | 아니오 (No) |
| tracing.sampleRate | 추적할 요청의 비율로, 0.0과 1.0 사이로 지정해요. Traefik은 parent 기반 샘플링 비율을 지원하므로, 루트 스팬(즉 Traefik이 시작한 스팬)은 이 비율대로 샘플링되고, 자식 스팬은 부모의 샘플링 결정(즉 들어오는 요청의 추적 컨텍스트)을 상속해요. 자세한 내용은 sampleRate를 참고하세요. | 1.0 | 아니오 (No) |
| tracing.capturedRequestHeaders | 속성으로 추가할 요청 헤더 목록을 정의해요. 클라이언트 및 서버 종류 스팬에 적용됩니다. | [] | 아니오 (No) |
| tracing.capturedResponseHeaders | 속성으로 추가할 응답 헤더 목록을 정의해요. 클라이언트 및 서버 종류 스팬에 적용됩니다. | [] | False |
| tracing.safeQueryParams | 기본적으로 모든 쿼리 파라미터는 수정(redact)돼요. 수정하지 않을 쿼리 파라미터 목록을 정의해요. | [] | 아니오 (No) |
| tracing.otlp.http | 익스포터가 HTTP를 사용해 OpenTelemetry 컬렉터로 추적을 보내도록 지시해요. 하위 옵션을 기본값으로 설정합니다. | null/false | 아니오 (No) |
| tracing.otlp.http.endpoint | 추적을 보낼 OpenTelemetry 컬렉터의 URL이에요. 형식="://:" | "https://localhost:4318" | 예 (Yes) |
| tracing.otlp.http.headers | 익스포터가 추적과 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. | | 아니오 (No) |
| tracing.otlp.http.tls.ca | OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | "" | 아니오 (No) |
| tracing.otlp.http.tls.cert | OpenTelemetry 컬렉터와의 보안 연결에 사용하는 공개 인증서의 경로예요. 이 옵션을 사용할 때는 key 옵션을 설정해야 합니다. | "" | 아니오 (No) |
| tracing.otlp.http.tls.key | TLS 연결에 사용하는 개인 키의 경로를 정의해요. | "" | 아니오 (No) |
| tracing.otlp.http.tls.insecureskipverify | insecureSkipVerify가 true면 OpenTelemetry 컬렉터와의 TLS 연결이 서버가 제시하는 인증서를 호스트명과 관계없이 수락해요. | false | 예 (Yes) |
| tracing.otlp.grpc | 익스포터가 gRPC를 사용해 OpenTelemetry 컬렉터로 추적을 보내도록 지시해요. | false | 아니오 (No) |
| tracing.otlp.grpc.endpoint | 추적을 보낼 OpenTelemetry 컬렉터의 주소예요. 형식=":" | "localhost:4317" | 예 (Yes) |
| tracing.otlp.grpc.headers | 익스포터가 추적과 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. | [] | 아니오 (No) |
| tracing.otlp.grpc.insecure | 익스포터가 보안 프로토콜 없이 OpenTelemetry 컬렉터로 추적을 보낼 수 있게 해 줘요. | false | 예 (Yes) |
| tracing.otlp.grpc.tls.ca | OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | "" | 아니오 (No) |
| tracing.otlp.grpc.tls.cert | OpenTelemetry 컬렉터와의 보안 연결에 사용하는 공개 인증서의 경로예요. 이 옵션을 사용할 때는 key 옵션을 설정해야 합니다. | "" | 아니오 (No) |
| tracing.otlp.grpc.tls.key | TLS 연결에 사용하는 개인 키의 경로를 정의해요. | "" | 아니오 (No) |
| tracing.otlp.grpc.tls.insecureskipverify | insecureSkipVerify가 true면 OpenTelemetry 컬렉터와의 TLS 연결이 서버가 제시하는 인증서를 호스트명과 관계없이 수락해요. | false | 예 (Yes) |
sampleRate
sampleRate 옵션은 ParentBased(TraceIDRatioBased) 전략으로 추적 샘플링을 제어해요.
샘플링 전략 동작 (Sampling Strategy Behavior)
-
루트 스팬 (Traefik에서 시작된 트레이스): trace ID 비율 기반 샘플링으로 구성된 sampleRate에 따라 샘플링돼요.
-
자식 스팬 (기존 추적 컨텍스트가 있는 요청): 로컬 sampleRate와 관계없이 부모 스팬의 샘플링 결정을 상속해요.
이렇게 하면 분산 트레이스 전반에 걸쳐 일관된 샘플링 결정이 보장돼요. 일단 트레이스가 샘플링되면 그 트레이스의 모든 스팬이 샘플링되어 완전한 종단 간(end-to-end) 가시성을 제공하죠.
resourceAttributes
resourceAttributes 옵션은 트레이스와 함께 보내는 리소스 속성을 설정하게 해 줘요.
Traefik은 리소스 속성을 설정하기 위해 OTEL_RESOURCE_ATTRIBUTES 환경 변수도 지원해요.
Kubernetes 리소스 속성 감지 (Kubernetes Resource Attributes Detection)
추가로 Traefik은 Kubernetes 클러스터에서 실행될 때 다음 Kubernetes 리소스 속성을 자동으로 발견해요:
-
k8s.namespace.name
-
k8s.pod.uid
-
k8s.pod.name
이 자동 감지는 예를 들어 Traefik 파드가 호스트 네트워크 모드로 실행되는 경우처럼 실패할 수 있다는 점을 주의하세요. 그런 경우 옵션이나 환경 변수로 속성을 직접 제공해야 해요.