01
헤더 하나를 붙여넣거나 경계값 예시를 불러오기
입력을 멈춘 지 300ms 후 자동으로 파싱됩니다 — 자동 파싱을 끄지 않는 한 버튼을 누를 필요가 없습니다. 세 개의 예시 버튼은 무작위로 고른 게 아니라 유효한 헤더, version ff 헤더, trace-id가 전부 0인 헤더를 각각 불러오는데, 이는 규격이 이름까지 짚어 언급하는 세 가지 경계 사례입니다.
- Ctrl/Cmd+Enter를 누르면 디바운스를 건너뛰고 즉시 파싱됩니다
Logs & Observability
traceparent 파서및 W3C Trace Context 검증 도구
traceparent 헤더를 붙여넣으면 version, trace-id, parent-id, trace-flags를 필드별로 해석해서 보여줍니다. 여러 헤더를 한 번에 검사하는 배치 모드나 테스트용 헤더를 만드는 생성 모드로도 전환할 수 있습니다.
traceparent 파서
파싱과 생성 모두 브라우저 안에서만 처리됩니다. 업로드되거나 트레이싱 백엔드로 전송되지 않습니다.
traceparent 헤더를 붙여넣거나 예시를 불러와 시작하세요.
traceparent 헤더는 하이픈으로 구분된 네 개의 필드일 뿐이라 단순해 보이지만, 어떤 서비스의 로그에는 trace-id가 전부 0으로 찍혀 있거나 중간의 프록시가 규격에서 명시적으로 금지한 버전 값으로 슬쩍 바꿔버리는 경우가 있습니다. 이 traceparent 파서는 실제 W3C Trace Context 문법에 따라 각 필드를 검증하므로, 단순히 낯설게 보이는 것과 실제로 잘못된 헤더를 구분할 수 있습니다.
두 서비스 사이에서 트레이스가 끊겼을 때 헤더 자체가 문제인지 확인하고 싶을 때, 수동으로 헤더 전파를 구현하면서 테스트용 헤더가 필요할 때, 로그에 쌓인 수많은 traceparent 값을 하나씩 눈으로 확인하는 대신 한꺼번에 검사하고 싶을 때 사용하세요.
이 traceparent 파서를 쓰는 이유
이미 유효한 헤더를 예쁘게 보여주기 위해서가 아니라, 실제 헤더 버그를 찾아내기 위해 만들었습니다.
모든 필드를 색으로 구분해 해석
이 traceparent 파서는 헤더를 version, trace-id, parent-id, trace-flags로 나누고 각각 다른 색으로 표시합니다. flags 바이트는 샘플링 여부와 예약 비트가 예상치 못하게 설정되어 있는지까지 평이한 말로 풀어서 보여줍니다.
규격이 명시적으로 금지하는 세 가지 경우를 정확히 잡아냄
version ff, 전부 0인 trace-id, 전부 0인 parent-id는 형식만 보면 16진수처럼 보이지만 W3C Trace Context에서 명시적으로 금지됩니다. 이 traceparent 파서는 길이와 문자 집합만 확인하는 게 아니라 이 세 가지를 이름까지 짚어서 알려줍니다.
훑어보는 것만으로는 알 수 없는 검증 항목
운영 로그에서 헤더를 붙여넣기 전에 알아두면 좋은 세 가지입니다.
02
tracestate를 추가하거나 일괄 검증 모드로 전환하기
모든 헤더가 tracestate를 갖는 것은 아니므로 tracestate 입력란은 기본적으로 접혀 있습니다. 켜면 vendor=value 쌍을 규격의 32개 멤버 제한과 256자 제한에 맞춰 검증합니다. 헤더 하나가 아니라 로그 전체를 확인하려면 일괄 검증 모드로 전환해 한 줄에 하나씩 붙여넣으세요.
- 일괄 검증 모드는 일부러 수동 실행으로 만들었습니다 — 붙여넣는 중간에 매번 다시 실행되면 오히려 방해가 되기 때문입니다
03
필드별 결과를 확인한 뒤 복사하거나 내보내기
version 00 헤더는 완전히 검증됩니다. 그보다 높은 버전은 네 필드는 해석되지만 뒤에 붙은 추가 데이터는 그대로 표시될 뿐 해석되지 않습니다. 입력을 수정하는 순간 복사와 다운로드가 비활성화되므로, 오래된 결과를 실수로 내보낼 일이 없습니다.
- 생성 모드로 전환하면 테스트 요청에 쓸 규격에 맞는 새 traceparent를 바로 만들 수 있습니다
파서와 생성기가 실제로 하는 일
하이픈 위치만 확인하는 정규식이 아니라, 진짜 W3C Trace Context 검증입니다.
네 필드 전체 분해
version, trace-id, parent-id, trace-flags를 각각 따로 해석하고 라벨을 붙이며, 샘플링 비트에 대한 평이한 설명도 함께 보여줍니다.
규격에 충실한 엄격한 검증
트레이싱 클라이언트를 따로 붙이지 않고도 trace id 검증기처럼 쓸 수 있습니다. version ff, 전부 0인 trace-id, 전부 0인 parent-id, 잘못된 필드 길이, 대문자 16진수를 모두 거부합니다 — 느슨한 정규식이라면 그냥 통과시켰을 경우들입니다.
줄 단위 요약이 포함된 일괄 검증
로그에서 발췌한 traceparent 값들을 한꺼번에 붙여넣으면 유효/무효/빈 줄 개수와 함께, 잘못된 줄마다 정확히 어떤 필드가 문제인지 알려줍니다.
tracestate 구조 검증
key=value 멤버를 규격의 key 문자 집합, tenant@vendor 형식, 256자 value 제한, 32개 멤버 제한, key 중복 금지 규칙에 맞춰 검증합니다.
규격에 맞는 테스트용 헤더 생성
암호학적으로 안전한 난수로 0이 아닌 trace-id와 parent-id를 만들어 version 00 traceparent를 생성하므로, 실수로 무효한 임시값으로 테스트할 일이 없습니다.
이 도구가 검증하는 것과 일부러 하지 않는 것
'검증 통과'를 '트레이싱이 정상'이라고 단정하기 전에 읽어보세요.
- 유효한 헤더가 트레이스의 실제 존재를 증명하지는 않습니다
- 이 도구는 문자열을 W3C Trace Context 문법에 맞춰 검증할 뿐입니다. Jaeger, Datadog, Honeycomb 등 어떤 백엔드에도 접속하지 않으므로, '유효함'은 '형식이 맞다'는 뜻일 뿐 '실제로 기록되었다'는 뜻이 아닙니다.
- W3C Trace Context만 지원합니다
- Zipkin의 B3 헤더, Google Cloud의 X-Cloud-Trace-Context, Sentry의 sentry-trace는 필드 개수와 구분자가 다릅니다. 이 파서는 이런 형식을 읽거나 변환하지 않습니다.
- 잘못된 입력은 보고만 하고, 조용히 고치지 않습니다
- 31자짜리 trace-id에 0을 채워 넣거나, 검증 전에 대문자 16진수를 소문자로 바꾸는 일은 하지 않습니다. 둘 다 실제로 트레이스 전파를 망가뜨리는 전형적인 실수이므로, 감추지 않고 그대로 드러냅니다.
- 일괄 입력은 최대 500줄까지
- 모든 처리는 브라우저 탭 안에서 이루어지므로, 매우 큰 로그를 붙여넣으면 기기의 사용 가능한 메모리에 제약을 받습니다. 더 큰 로그는 500줄 이하로 나눠서 검사하세요.
traceparent 파서 관련 자주 묻는 질문
W3C Trace Context 헤더를 디버깅하다 실제로 마주치는 질문들입니다.
trace-flags의 샘플링 플래그(01)는 정확히 무슨 의미인가요?
trace-flags는 16진수 2자리로 표현되는 1바이트이고, 비트 0이 샘플링 플래그입니다. 01은 호출자가 이 트레이스를 트레이싱 백엔드에 기록하도록 권장한다는 뜻이고, 00은 그렇지 않다는 뜻입니다. 이는 호출 체인을 따라 전달되는 권장 값일 뿐, 실제로 어떤 시스템이 이 트레이스를 기록했다는 보장은 아닙니다.
trace id와 span id의 차이는 무엇인가요?
trace-id는 분산 트레이스 전체를 유일하게 식별하는 값으로 요청이 지나가는 모든 서비스가 공유합니다. span-id(W3C 규격에서는 parent-id)는 체인 안의 한 구간을 식별하는 값으로, 서비스를 거칠 때마다 보통 새로운 값이 되지만 같은 trace-id를 공유합니다.
traceparent와 tracestate는 어떻게 다른가요?
traceparent는 version, trace-id, parent-id, trace-flags라는 네 개의 필수 필드를 담고 있으며, W3C를 따르는 모든 시스템이 이해할 수 있어야 합니다. tracestate는 선택 항목으로, 개별 트레이싱 벤더가 다른 시스템의 이해를 요구하지 않고 자체적인 key=value 데이터를 덧붙일 수 있게 해줍니다.
traceparent의 version이 ff이면 왜 금지되나요?
W3C Trace Context 규격은 ff를 미래 버전 번호와 혼동되지 않도록 예약해 두었기 때문에, 헤더의 나머지 부분이 아무리 올바른 형식이어도 명시적으로 금지됩니다. 이 도구는 이를 단순한 16진수 2자리가 아니라 version ff 문제로 이름까지 짚어 알려줍니다.
trace id가 전부 0이면 왜 무효인가요?
전부 0인 trace-id는 아무것도 식별할 수 없기 때문에 규격에서 명시적으로 금지합니다. '32개의 0'은 16진수 형식 검사만 보면 통과하지만 그래도 무효입니다. parent-id(span-id)가 전부 0인 경우도 마찬가지로 무효입니다.
잘못된 W3C Trace Context 헤더는 어떻게 고치나요?
먼저 이 도구로 파싱해서 정확히 어떤 필드가 문제이고 왜 그런지 확인하세요. 실제 문제의 대부분은 프록시나 로깅 파이프라인이 헤더를 잘라내거나, 대문자 16진수를 섞어 넣거나, 실제로 생성한 ID 대신 전부 0 같은 템플릿 값을 그대로 전달해버리는 경우에서 발생합니다.
이 파서가 잘못 판단한 헤더를 발견했나요?
지금 traceparent 파서 사용하기
traceparent 헤더를 파싱하거나, 여러 개를 한 번에 검증하거나, 테스트용 새 헤더를 생성해보세요 — 모두 브라우저 안에서 처리되며 업로드되는 내용은 없습니다.
서비스 사이에서 트레이스가 끊길 다음번을 위해 즐겨찾기에 추가해두세요.
HeyUtils의 개발 및 운영 도구 카테고리에 속합니다.