OpenTelemetry 모범 사례: 계측, Collector 배치, 샘플링
요청 하나를 계측에서 저장까지 따라가며 리소스 속성, 컨텍스트 전파, Collector 배치와 샘플링 정책을 검토하는 방법을 살펴봅니다.
결제 트레이스에 HTTP 서버 스팬과 데이터베이스 호출이 보이는데 주문이 거절된 이유는 알 수 없습니다. 샘플링 비율을 낮춘 뒤에는 조사하려던 실패 트레이스 자체가 보이지 않습니다. 앞의 문제는 애플리케이션이 무엇을 기록했는지, 뒤의 문제는 파이프라인이 무엇을 남겼는지에 달려 있습니다.
이 글은 요청 하나를 계측에서 저장까지 따라가며 OpenTelemetry 모범 사례를 설명합니다. 자동 계측을 어디까지 쓰고 무엇을 보완할지, Collector를 어디에 둘지, 어떤 단계에서 샘플링할지 차례로 살펴봅니다.
런타임이 지원하는 계측부터 적용하기
Java Agent는 지원하는 라이브러리를 런타임에 계측할 수 있습니다. Python의 제로 코드 계측과 Node.js 계측 패키지는 지원 라이브러리와 신호 범위가 각각 다릅니다. 애플리케이션에서 쓰는 버전을 확인하고 백엔드에 실제로 들어온 데이터를 살펴보세요. HTTP 스팬은 요청의 실패를 보여 줄 수 있지만 결제 거절인지 재고 예약 만료인지는 애플리케이션이 기록해야 합니다.
기존 계측으로 설명하기 어려운 구간에 커스텀 스팬을 추가합니다. 결과는 accepted, declined, timeout처럼 정해진 값으로 남깁니다. 필요한 스팬이 이미 있다면 라이브러리가 허용하는 범위에서 그 스팬에 속성을 추가합니다. 프로바이더를 직접 초기화하기 전에 사용하는 계측 패키지나 배포판에서 이미 초기화하는지 확인하세요. OpenTelemetry 제로 코드 계측(영어)
서비스 이름을 안정적으로 유지하고 컨텍스트 전달하기
리소스는 텔레메트리를 생성한 대상을 나타냅니다. service.name에는 논리적인 서비스 이름을, service.version에는 버전을 설정합니다. 환경에는 현재 시맨틱 규약의 deployment.environment.name을 사용합니다. 복제본이나 릴리스가 바뀌어도 서비스 이름은 유지합니다. 표준 SDK 환경 변수를 지원하는 런타임에서 스테이징 환경을 설정하는 예는 다음과 같습니다.
export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.8.0,deployment.environment.name=staging
설정한 값이 백엔드에 어떻게 저장됐는지 확인합니다. 작업에만 해당하는 정보는 스팬에 기록하고, 요청 ID처럼 카디널리티가 높은 값은 메트릭 차원에서 제외합니다. 서비스 경계에서 송신 측이 트레이스 컨텍스트를 주입하고 수신 측이 추출하는지 확인하세요. Baggage는 따로 전파되며 스팬 속성으로 자동 변환되지 않습니다. 여기에 인증 정보나 개인정보를 넣지 않습니다. 배포 환경 리소스 규약(영어) · OpenTelemetry Baggage(영어) · 컨텍스트 전파
역할에 맞춰 Collector 배치하기
백엔드가 SDK의 신호, 프로토콜, 인증 방식을 지원하면 직접 전송할 수 있습니다. 호스트의 데이터를 수집하거나 워크로드 가까이에 수신 지점을 두려면 에이전트 형태의 Collector를 사용할 수 있습니다. 여러 서비스에 같은 처리 또는 라우팅 정책을 적용하려면 게이트웨이가 유용합니다. 두 형태를 함께 쓸 경우 각 단계의 역할을 정하고 전송 경로 전체를 모니터링합니다. Collector 배포 패턴(영어)
배치 처리로 전송 요청을 합칠 수 있습니다. 전송 큐와 재시도가 짧은 중단을 버틸 수 있는지는 익스포터, 큐 용량, 재시도 설정에 따라 다릅니다. 메모리에 남은 큐 데이터는 프로세스가 종료되면 사라집니다. 영구 저장소를 쓰는 큐도 재시작 후 해당 저장소에 접근할 수 있어야 합니다. 큐 사용량, 수신 거부, 전송 실패를 함께 봅니다. 신뢰 경계를 넘기 전에 민감한 필드를 걸러 내고 실제 전송 데이터를 확인하세요. Collector 복원력(영어) · Collector 모니터링
판단에 필요한 정보가 모이는 단계에서 샘플링하기
헤드 샘플링은 요청 처리 초기에 결정합니다. 부모의 결정을 자식 스팬에 전달하고, 새로운 루트에는 확률 기반 규칙을 적용할 수 있습니다. 테일 샘플링은 스팬을 받은 뒤 오류나 지연 시간을 조건으로 판단합니다. SDK에서 이미 버린 스팬은 나중에 오류가 발견돼도 복원할 수 없습니다.
여러 Collector에서 테일 샘플링을 한다면 같은 트레이스 ID의 스팬을 같은 샘플링 인스턴스로 보냅니다. 일반적인 요청 부하 분산은 한 트레이스를 여러 복제본으로 나눌 수 있습니다. 결정을 늦추기 전에 스팬의 도착 지연과 큐 용량, 메모리 사용량을 확인하세요. 애플리케이션의 요청 수와 오류 수는 별도 경로로 집계할 수 있습니다. 스팬에서 메트릭을 생성할 때는 집계 전에 적용되는 샘플링과 필터를 확인합니다. OpenTelemetry 샘플링(영어) · 트레이스 기반 Collector 라우팅(영어)
요청 하나를 백엔드까지 확인하기
DataKit OpenTelemetry 수신 설정(영어)에 따라 익스포터와 수신기의 OTLP 전송 방식을 맞춥니다. HTTP를 사용한다면 신호별 수신 경로도 확인합니다. 진입 서비스에서 테스트 요청을 보내고 Guance 트레이스 상세 화면(영어)에서 동기 호출의 트레이스 ID와 부모 스팬 관계, 서비스 이름과 환경, 버전을 확인합니다.
중간 스팬이 보이지 않으면 계측 범위, 컨텍스트 전파, 샘플링, 전송을 차례로 확인합니다. 수신기나 백엔드를 교체했다면 기존 처리 및 샘플링 규칙도 별도로 검증합니다. 자동 계측의 부하는 같은 워크로드에서 활성화 전후의 시작 시간, 지연, 리소스 사용량을 비교해 판단합니다.
관련 글 · OpenTelemetry란? · Collector에서 민감 데이터 가리기
