traceparent 디코더 — W3C Trace Context

traceparent 헤더란?

# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate:  rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

# Read the four fields apart
#   version     00
#   trace-id    4bf92f3577b34da6a3ce929d0e0e4736   (16 bytes, whole request)
#   parent-id   00f067aa0ba902b7                   (8 bytes, calling span)
#   trace-flags 01                                 (bit 0 set = sampled)

# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
       https://example.com/api

주요 기능

traceparent 해석 예시

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

유효한 헤더 · sampled 비트 꺼짐

00-00000000000000000000000000000000-00f067aa0ba902b7-01

무효 — trace-id가 전부 0

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

traceparent 디코더 사용법

1. 1

   traceparent 헤더 붙여넣기

   원본 헤더 값을 그대로 넣으십시오. 예: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. 입력과 동시에 해석되므로 누를 버튼이 없습니다.

2. 2

   네 필드를 따로 읽기

   version, trace-id, parent-id, trace-flags가 각자의 행으로 나뉘고 행마다 복사 버튼이 붙습니다. 32자를 손으로 드래그하지 않고도 trace ID만 쿼리로 가져갈 수 있습니다.

3. 3

   플래그를 비트 단위로 확인하기

   trace-flags 바이트를 마스크와 함께 8비트 전부로 펼칩니다. sampled와 Level 2의 random-trace-id 플래그가 두 글자 값 속에 묻히지 않고 각각 드러납니다.

4. 4

   사용하는 백엔드 형식으로 변환하기

   Datadog, AWS X-Ray, B3의 두 형태가 아래에 생성됩니다. Datadog이 기대하는 하위 64비트 10진 trace ID와 함께 전달되는 상위 64비트 태그도 포함됩니다.

5. 5

   tracestate를 더하고 결과 공유하기

   tracestate 헤더를 붙여넣으면 멤버가 개별 검증과 함께 나열되고 32개 상한 대비 개수가 표시됩니다. 그다음 링크 복사로 현재 상태를 그대로 URL에 담아 티켓에 붙일 수 있습니다.

traceparent에서 흔한 실수

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

traceparent 디코더로 할 수 있는 일

추적에 span이 없는 이유 파악하기

들어온 헤더를 붙여넣고 sampled 비트를 읽으십시오. 꺼져 있다면 그 추적은 애초에 기록될 예정이 없었고, 답은 내 계측이 아니라 호출자 쪽에 있습니다. 이 구분 하나로 내 샘플러 설정을 뒤지는 시간을 크게 아낄 수 있습니다.

백엔드가 찾지 못하는 추적 찾아내기

애플리케이션 로그에서 복사한 trace ID가 Datadog에서 아무것도 반환하지 않는다면 대개 형식이 원인입니다. 여기서 변환하면 API가 기대하는 하위 64비트 10진 식별자와 함께 붙여야 하는 상위 64비트 태그를 확인할 수 있습니다.

게이트웨이가 주입하는 헤더 검증하기

프록시와 서비스 메시는 유입 시점에 추적 컨텍스트를 생성합니다. 실제로 도착한 값을 붙여넣어 길이, 소문자 16진, 0이 아닌 식별자를 먼저 확인한 뒤에 하위 탓이라고 판단하십시오.

운영 추적을 손으로 재현하기

실제 요청의 헤더를 가져와 스테이징 엔드포인트에 재생하면 같은 추적을 따라갈 수 있습니다. 요청은 curl 명령 빌더로 조립하고 헤더를 그대로 붙여 넣으십시오.

팀에 trace context 설명하기

이 페이지의 필드 해부 표와 trace-flags 표는 그대로 가리키며 설명할 수 있는 정적 참고 자료이고, 프리셋 칩은 누군가 서비스를 망가뜨리지 않고도 각 실패 유형을 보여 줍니다.

W3C Trace Context 검증기의 동작 방식

네 필드 문법

version "-" trace-id "-" parent-id "-" trace-flags이며 전부 소문자 16진입니다. version은 2자리, trace-id는 32자리, parent-id는 16자리, trace-flags는 2자리로, 16진 52자리에 하이픈 3개를 더해 version 00 기준 정확히 55자입니다. 값이 맞아 보여도 대문자 16진은 헤더를 무효로 만듭니다. 또한 전부 0인 trace-id와 전부 0인 parent-id는 비어 있는 것이 아니라 명시적으로 무효입니다.

trace-flags는 비트 필드

비트 0(마스크 0x01)은 sampled로, 켜져 있으면 호출자가 추적 데이터를 기록했을 수 있다는 뜻입니다. Level 2에서 도입된 비트 1(마스크 0x02)은 random-trace-id로, 켜져 있으면 trace-id의 최소한 오른쪽 7바이트가 균일 분포의 난수로 선택되었어야 하며, 덕분에 하위 시스템이 그 값으로 샘플링하거나 샤딩할 수 있습니다. 비트 2부터 7까지는 예약이며 수신 시 무시하고 송신 시 지워야 합니다. 예약 비트가 있을 수 있으므로 이 필드는 비트 AND로 검사해야 합니다. 0x01과의 동등 비교는 예약 비트까지 켜진 샘플링된 추적을 잘못 보고합니다.

미래 버전과의 전방 호환성

version은 오늘 00이고 ff는 금지지만, 나머지를 전부 거부하는 파서는 틀렸습니다. 명세는 버전이 더 높고 헤더 길이가 알려진 형식 이상일 때, 추적을 새로 시작하는 대신 해석을 시도해 알아볼 수 있는 필드를 읽고 남는 뒤쪽 데이터를 허용하도록 수신 측에 요구합니다. 이 디코더도 그 규칙을 따릅니다. 미래 버전은 해석에 성공하며 오류가 아니라 경고로 표시됩니다.

운영에서 발목을 잡는 tracestate 제한

리스트 멤버는 최대 32개입니다. 이는 문법상의 엄격한 경계여서, 이를 넘기면 헤더 자체가 무효가 되고 수신 측은 그것을 버립니다. 각 키는 최대 256자에 소문자나 숫자로 시작하며, Level 2부터 @는 테넌트 구분자가 아니라 평범한 키 문자입니다. 각 값은 1자에서 256자 사이의 출력 가능한 ASCII이고, 쉼표나 등호를 담을 수 없으며 비어 있어서도 안 됩니다. 키 중복은 무효이지만 빈 리스트 멤버는 명세가 명시적으로 허용합니다. 중간 노드가 항목을 지우고 남긴 끝의 쉼표도 여전히 유효한 헤더입니다. 이와 별개로 벤더는 합쳐진 헤더를 최소 512자까지 전파해야 하며, 그 예산에 맞추려고 잘라 낼 때는 128자가 넘는 항목부터 버려야 합니다. 장황한 벤더의 데이터가 간결한 벤더의 것보다 먼저 사라지는 이유가 바로 이것입니다.

Trace Context 모범 사례

플래그는 비트 AND로 검사하기

flags == 0x01이 아니라 flags & 0x01로 쓰십시오. 여덟 비트 중 여섯은 앞으로를 위해 예약되어 있고, 그중 하나라도 실제로 나타나는 순간부터 동등 비교는 샘플링된 추적을 잘못 보고하기 시작합니다.

전부 0인 ID는 파이프라인 고장으로 취급하기

너그럽게 넘길 빈 값이 아닙니다. 헤더를 거부하고, 트레이서 초기화에 실패했거나 자리표시자를 주입하고 있는 구성 요소를 찾아 나서십시오.

sampled 비트가 꺼져 있으면 상위를 보기

부모 기반 샘플러는 호출자의 결정을 전파합니다. 추적이 비어 있다면 내 설정을 감사하기 전에, 샘플링을 끈 부모 span을 보내는 서비스가 어디인지부터 특정하십시오.

tracestate는 짧게 유지하기

32개 상한은 문법상의 엄격한 경계입니다. 넘기는 순간 헤더가 무효가 됩니다. 이와 별개로 합쳐진 헤더는 512자까지만 전파가 보장되고, 잘라 낼 때는 128자가 넘는 항목부터 버려집니다. 긴 호출 사슬에서 살아남아야 하는 데이터라면 애초에 tracestate에 둘 것이 아닙니다.

trace ID를 JavaScript number로 로그에 남기지 않기

128비트 trace ID는 물론 64비트 Datadog 식별자조차 Number.MAX_SAFE_INTEGER를 넘습니다. 문자열로 유지하고 연산이 필요할 때만 BigInt로 변환하십시오. 그러지 않으면 끝자리가 조용히 망가집니다.

traceparent 디코더 자주 묻는 질문