OpenTelemetry 컨텍스트 전파와 traceparent
traceparent, tracestate, Baggage의 역할과 HTTP, gRPC, 메시지 큐에서 끊어진 트레이스를 확인하는 방법을 살펴봅니다.
체크아웃 스팬은 보이는데 재고 요청 스팬은 다른 트레이스 ID로 기록되어 있습니다. 두 서비스 모두 스팬을 정상적으로 내보내도 이런 일이 생깁니다. 먼저 재고 서비스가 체크아웃에서 보낸 컨텍스트를 추출했는지 확인합니다.
OpenTelemetry 컨텍스트 전파는 서비스 경계를 넘어 트레이스 식별 정보를 전달합니다. 수신 측은 스팬을 시작하기 전에 컨텍스트를 추출하고, 발신 측은 다음 호출을 보내기 전에 현재 스팬의 컨텍스트를 주입합니다. 이 두 단계가 맞아야 나중에 부모 관계를 따라갈 수 있습니다.
전송되는 정보
SpanContext에는 트레이스 ID, 현재 스팬 ID, 트레이스 플래그, 트레이스 상태가 들어 있습니다. 추출한 원격 컨텍스트에서 자식 스팬을 시작하면 트레이스 ID는 이어지고 새 스팬 ID가 생깁니다. 자식의 부모는 발신 측 스팬입니다. 시작 시각과 종료 시각은 개별 스팬에 기록됩니다. SDK는 추출한 스팬 컨텍스트를 원격으로 표시합니다. 이 표시는 SDK 컨텍스트에 남습니다. OpenTelemetry SpanContext API(영어)
Baggage는 별도의 전파기가 처리하는 선택적 키-값 데이터입니다. 스팬 속성에 자동으로 들어가지는 않습니다. 예를 들어 배포 그룹별로 검색하려면, 전송이 허용된 그룹 값을 애플리케이션에서 스팬 속성으로 명시적으로 복사할 수 있습니다.
traceparent 헤더 읽기
W3C Trace Context Level 1 권고안(영어)의 00 형식은 version-trace-id-parent-id-trace-flags 순서입니다. 다음 HTTP 헤더를 예로 들어 보겠습니다.
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
| 필드 | 수신 측에서의 의미 |
|---|---|
00 |
형식 버전입니다. ff는 유효하지 않습니다. 이후 버전을 받으면 Level 1에 따라 해석할 수 있는 앞부분의 파싱을 시도합니다. |
4bf92f3577b34da6a3ce929d0e0e4736 |
트레이스 ID입니다. 소문자 16진수 32자리이며 모두 0인 값은 유효하지 않습니다. |
00f067aa0ba902b7 |
발신 측에서 전달한 스팬 ID입니다. 소문자 16진수 16자리이며 모두 0인 값은 유효하지 않습니다. |
01 |
1바이트 플래그입니다. 최하위 비트인 0x01이 샘플링 플래그입니다. 실제로 검색 가능한지는 내보내기와 저장 설정에도 달려 있습니다. |
선택적인 tracestate 헤더는 공급업체별 항목을 순서대로 담아 유효한 traceparent와 함께 전달합니다. 양쪽에서 호환되는 전파기를 쓰는지 확인하세요. OTEL_PROPAGATORS를 지원하는 구현의 명세상 기본값은 tracecontext,baggage입니다. SDK를 수동으로 구성할 때는 전파기를 명시적으로 설정합니다. OpenTelemetry 전파기 API(영어) · SDK 환경 변수(영어)
HTTP, gRPC, 메시지 큐에서 전파하기
HTTP. 클라이언트 계측이 요청 헤더에 컨텍스트를 주입합니다. 서버 미들웨어는 서버 스팬을 시작하기 전에 헤더에서 컨텍스트를 추출합니다. 스팬을 시작하면서 반환된 컨텍스트를 다음 호출에 전달하세요. 이전 컨텍스트로 요청을 만들면 헤더 형식이 맞아도 부모 스팬이 어긋날 수 있습니다.
gRPC. 클라이언트와 서버 계측은 HTTP/2 헤더로 전달되는 RPC 메타데이터를 사용합니다. 인터셉터나 프록시를 거치는 호출이라면 수신 측 메타데이터도 살펴봅니다. gRPC 메타데이터 안내(영어)
메시지 큐. 프로듀서는 메시지 생성 컨텍스트를 Kafka 레코드 헤더 같은 메시지 전달 매체에 넣습니다. 배치를 처리하는 컨슈머는 메시지별 컨텍스트를 추출하고 처리 스팬에서 각 컨텍스트로 링크를 만들 수 있습니다. 스팬에는 부모를 하나만 지정할 수 있어, 배치에서 한 메시지의 생성 스팬만 부모로 삼으면 나머지 관계를 잃습니다. OpenTelemetry 메시징 규약에서는 기본적으로 Span Link를 사용합니다. 메시지 한 건을 처리할 때는 계측 구현에 따라 생성 컨텍스트를 처리 스팬의 부모로 지정할 수도 있습니다. HTTP 핸들러 등 이미 활성 스팬이 있는 범위에서 처리한다면 그 스팬을 부모로 유지하고 메시지 생성 컨텍스트를 링크합니다. 메시징 스팬 규약(영어)
사용자 정의 프로토콜. 메시지 필드를 전파기가 읽고 쓸 수 있는 전달 매체로 연결합니다. 주입과 추출을 수행한 뒤 수신 측에서 반환된 컨텍스트로 스팬을 시작합니다.
끊어진 경계 좁히기
테스트 요청 하나를 보내고, 동기 호출마다 발신 측 traceparent를 다음 서비스가 추출한 컨텍스트와 비교합니다. 수신 측 서버 스팬이 같은 트레이스 ID를 갖는지, 발신 스팬을 부모로 삼았는지 확인합니다. 큐에서는 부모 ID와 링크를 함께 봅니다. 링크를 사용하는 컨슈머는 다른 트레이스 ID를 가질 수 있습니다.
예상과 달리 ID가 바뀌었다면 헤더를 제거하는 게이트웨이, 계측하지 않은 클라이언트, 빈 컨텍스트에서 시작된 비동기 작업을 살펴봅니다. 공개 진입점에서 신뢰 경계 정책에 따라 의도적으로 새 트레이스를 만드는 경우도 있습니다. ID가 맞는데도 스팬이 보이지 않으면 기록, 샘플링, 내보내기를 확인하고 백엔드 조회 기간과 필터도 점검합니다.
Guance에서 트레이스와 로그 맞춰 보기
DataKit OTLP 수신기(영어)로 스팬을 보낸 뒤 테스트 트레이스를 찾아 동기 호출의 부모 ID를 확인합니다. 비동기 처리에서는 계측 출력에서 처리 스팬의 링크를 대조합니다.
같은 요청의 로그를 보려면 애플리케이션 로그에 현재 트레이스 ID를 넣고 APM과 로그 연계를 설정합니다. 로그에 트레이스 ID가 있는데 대응하는 스팬이 조회되지 않는다면, 해당 구간의 샘플링과 내보내기 상태를 확인합니다.
Baggage가 나가는 범위 정하기
외부로 나가는 호출마다 어떤 전파기가 실행되는지 확인하세요. 계측된 클라이언트가 외부 서비스를 호출하면 Baggage가 조직 밖으로 전달될 수 있습니다. 전송 키를 허용 목록으로 제한하고 인증 정보와 개인정보를 제외합니다. 들어온 값도 신뢰하지 않고 검증합니다. 접근 권한은 서비스 인증과 애플리케이션 인가에서 결정합니다. W3C Baggage(영어)
더 읽기 · OpenTelemetry란? · OpenTelemetry 샘플링(영어)
