---
title: "트레이스 ID와 스팬 ID 차이, 실제 traceparent 헤더로 해석하기"
description: "트레이스 ID는 요청 1건이 거치는 모든 서비스에서 그 요청을 같은 값으로 가리켜요. 스팬 ID는 단계 1개를 가리키므로 서비스마다 새로 만들어져요."
canonical: "https://logbrew.co/ko/guides/trace-id"
last_updated: "2026-11-21"
---

# 트레이스 ID와 스팬 ID 차이, 실제 traceparent 헤더로 해석하기

트레이스 ID는 요청 1건이 거치는 모든 서비스에서 그 요청을 같은 값으로 가리켜요. 스팬 ID는 단계 1개를 가리키므로 서비스마다 새로 만들어져요.

Node.js 22.18.0, @logbrew/node 0.1.30, Python 3.13.9, FastAPI 0.165.0, uvicorn 0.54.0, logbrew-fastapi 0.1.14, curl 8.7.1 및 logbrew CLI 0.1.96 환경에서 2026년 11월 21일에 테스트

글 [Furkan Erday](https://github.com/furkanerday). LogBrew 창업자 Furkan Erday. 매일 Claude Code와 Codex로 LogBrew를 만들어요.

Canonical: https://logbrew.co/ko/guides/trace-id

## traceparent 헤더별로 트레이스가 어떻게 됐는지

| curl이 보낸 헤더 | 트레이스 ID 유지 | 두 로그가 같은 트레이스 ID |
| --- | --- | --- |
| 유효, 플래그 `01` | 예 | 예 |
| 유효, 플래그 `00` | 예 | 예 |
| 대문자 트레이스 ID | 예, 소문자로 바뀜 | 예 |
| 모두 0인 트레이스 ID | 새 트레이스 | 예 |
| 버전 `ff` | 새 트레이스 | 예 |
| 헤더 없음 | 새 트레이스 | 예 |

FastAPI 서비스를 호출하는 Node.js 서비스에 보낸 요청 6건. @logbrew/node 0.1.30과 logbrew-fastapi 0.1.14 사용.

## traceparent 헤더 해석하기

### 헤더를 하이픈으로 나누기

`traceparent`에는 `-`로 나뉜 소문자 16진수 필드 4개가 있어요. 버전, 트레이스 ID, 부모 ID, 트레이스 플래그예요. 이것이 curl이 `checkout` 서비스에 보낸 헤더예요.

출력

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
```

### 버전 읽기

W3C Trace Context 권고안의 버전은 `00` 하나뿐이고 `ff`는 유효하지 않아요. `ff`를 보내자 두 SDK 모두 헤더를 무시하고 새 트레이스를 시작했어요.

### 트레이스 ID 읽기

다음 32자는 트레이스 ID로, 16바이트 16진수 `9095c7b7bf222836f82c2c415bc2bd65`예요. 요청 전체를 가리키고, 모든 서비스가 바꾸지 않고 전달해요. 모두 0인 트레이스 ID는 유효하지 않아요.

### 부모 ID 읽기

다음 16자는 부모 ID로, 8바이트 16진수 `fe8e70882fecdf07`이에요. 호출한 쪽 스팬의 스팬 ID라서 홉마다 바뀌어요. 모두 0인 부모 ID는 유효하지 않아요.

### 트레이스 플래그 읽기

마지막 2자는 플래그이고, 의미가 있는 건 비트 0뿐이에요. `01`은 호출한 쪽이 트레이스를 기록했을 수 있다는 뜻이고, `00`은 기록하지 않았다는 뜻이에요. `00`이어도 두 SDK는 스팬을 보냈고, LogBrew는 트레이스를 보여 줬어요.

## Node.js에서 Python으로 트레이스 넘기기

### SDK 2개 설치하기

`checkout` 서비스는 `@logbrew/node`를 쓰는 Node.js 서비스예요. 이 서비스가 `logbrew-fastapi`를 쓰는 FastAPI 앱 `payments`를 호출해요. 두 서비스 모두 LogBrew 프로젝트의 서버 키를 쓰세요.

```bash
npm install @logbrew/sdk @logbrew/node
python3 -m pip install logbrew-sdk logbrew-fastapi
```

### Node.js 서버와 호출 감싸기

`withLogBrewHttpHandler()`는 요청마다 `traceparent`를 읽고 스팬을 시작해요. `fetchWithLogBrewSpan()`은 호출용 자식 스팬을 시작하고, 그 스팬의 ID로 새 `traceparent`를 써요. 래퍼는 `LOGBREW_SERVER_API_KEY`에서 키를 읽어요.

```bash
import { createServer } from "node:http";
import { fetchWithLogBrewSpan, withLogBrewHttpHandler } from "@logbrew/node";

const server = createServer(withLogBrewHttpHandler(async (req, res, logbrew) => {
  logbrew.client.log(`evt_checkout_${Date.now()}`, new Date().toISOString(), {
    message: "checkout started for order 1042",
    level: "info",
    logger: "checkout"
  });
  const reply = await fetchWithLogBrewSpan("http://127.0.0.1:28702/payments/1042", {
    method: "POST"
  }, {
    client: logbrew.client,
    trace: logbrew.trace,
    routeTemplate: "/payments/:orderId"
  });
  res.writeHead(reply.status, { "content-type": "application/json" });
  res.end(await reply.text());
}));

server.listen(28701, "127.0.0.1");
```

### FastAPI 앱에 LogBrew 추가하기

`init_logbrew()`는 요청마다 `traceparent`를 읽고 자식 스팬을 시작해요. `logbrew.logging_handler`는 로그 레코드마다 요청의 트레이스 ID와 스팬 ID를 붙여요.

```bash
import logging
import os

from fastapi import FastAPI
from logbrew_fastapi import init_logbrew

app = FastAPI()
logbrew = init_logbrew(
    app, api_key=os.environ["LOGBREW_SERVER_API_KEY"], service_name="payments"
)
logger = logging.getLogger("payments")
logger.setLevel(logging.INFO)
logger.addHandler(logbrew.logging_handler)


@app.post("/payments/{order_id}")
def authorize(order_id: str):
    logger.warning("card declined for order %s", order_id)
    return {"orderId": order_id, "status": "declined"}
```

## 로그 한 줄의 트레이스 찾기

### 두 서비스를 거치는 요청 1건 보내기

curl이 `traceparent`를 보냈어요. `checkout` 앞의 브라우저나 게이트웨이도 이렇게 보낼 수 있어요. 헤더가 없으면 `checkout`이 새 트레이스를 시작해요.

```bash
curl -X POST http://127.0.0.1:28701/checkout \
  -H 'traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01'
```

출력

```text
{"orderId":"1042","status":"declined"}
```

### 홉마다 헤더 비교하기

서비스마다 헤더를 출력했어요. `checkout`은 트레이스 ID를 유지하고, 부모 ID에 자기 호출 스팬의 ID `1a95bcb4e3fcb3ce`를 넣었어요. `payments`는 그 헤더를 읽고 그 아래에 스팬 `bc7e3f490d4a4d00`을 시작했어요.

출력

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
checkout sent traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
payments got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
```

### 트레이스의 모든 로그 찾기

아무 로그 줄에서 트레이스 ID를 복사해 `--trace`에 넘기세요. CLI는 서비스마다 로그를 돌려줬어요. 대시보드에서는 로그의 검색창에 트레이스 ID를 붙여 넣으세요.

```bash
logbrew read logs --project "<project_id>" --trace 9095c7b7bf222836f82c2c415bc2bd65
```

출력

```text
Logs (2)
- warning card declined for order 1042 service=payments trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
- info checkout started for order 1042 service=checkout trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
```

### 트레이스 열기

이 트레이스에는 스팬이 3개 있어요. 2개는 `checkout`, 1개는 `payments`에서 왔어요. 대시보드에서는 탐색의 검색창에 트레이스 ID를 붙여 넣고 트레이스를 여세요.

```bash
logbrew read trace 9095c7b7bf222836f82c2c415bc2bd65 --project "<project_id>"
```

출력

```text
Trace 9095c7b7bf222836f82c2c415bc2bd65 spans=3 [unversioned / production]
- POST /payments/{order_id}
- POST /payments/:orderId
- POST /checkout
```

## 테스트에서 확인한 내용

`checkout`은 Node.js 22.18과 @logbrew/node 0.1.30으로, `payments`는 Python 3.13.9, FastAPI 0.165.0, uvicorn 0.54.0, logbrew-fastapi 0.1.14로 실행했어요. 둘 다 로컬 LogBrew 서버로 보냈어요. curl은 `checkout`에 요청 6건을 보냈어요. 5건은 서로 다른 `traceparent`를 담았고, 1건은 헤더가 없었어요.

모든 요청에서 두 서비스의 로그는 같은 트레이스 ID를 가졌어요. 헤더가 유효하면 curl이 보낸 트레이스 ID였어요. 헤더가 유효하지 않거나 없으면 `checkout`이 새 트레이스를 시작해 넘겼어요.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| `checkout` 요청 | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| `checkout`이 `payments`를 호출 | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| `payments` 요청 | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

- `checkout`
  - `level`: `info`
  - 메시지: `checkout started for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `5569d78d6d163d95`
- `payments`
  - `level`: `warning`
  - 메시지: `card declined for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `bc7e3f490d4a4d00`

## 트레이스 ID와 스팬 ID 차이

트레이스 ID는 16바이트이고 16진수 32자로 써요. 스팬 ID는 8바이트이고 16자로 써요. OpenTelemetry 트레이스 API 명세는 1바이트 이상이 0이 아닌 ID만 유효하다고 보고, 둘 다 소문자 16진수로 써요.

OpenTelemetry에서 스팬 컨텍스트는 트레이스 ID, 스팬 ID, 트레이스 플래그, 트레이스 상태를 담아요. `traceparent`는 앞의 3개를 실어요. 트레이스 상태는 벤더 항목을 최대 32개 담는 목록이고, `tracestate` 헤더가 실어요. LogBrew SDK는 둘 다 `tracestate`를 쓰지 않아요.

|  | 트레이스 ID | 스팬 ID |
| --- | --- | --- |
| 16진수 글자 수 | `32` | `16` |
| 홉마다 같음 | 예 | 아니요 |
| 모두 0이어도 유효 | 아니요 | 아니요 |

## 헤더가 잘못됐을 때

권고안은 소문자 16진수만 허용하고, 버전 `ff`와 모두 0인 ID를 금지해요. 이런 헤더를 받은 서비스는 헤더를 무시하고 새 트레이스를 시작해야 해요. 두 SDK 모두 `ff`, 그리고 모두 0인 트레이스 ID나 부모 ID에서 그렇게 했어요.

두 SDK 모두 대문자 트레이스 ID를 받아들이고 소문자로 바꿔 넘겼어요. 소문자로 보내세요. 엄격한 서비스는 대신 새 트레이스를 시작해요.

헤더가 없을 때 `checkout`은 플래그 `01`로, `payments`는 플래그 `00`으로 트레이스를 시작했어요. LogBrew는 두 트레이스를 모두 보관했어요.

| 트레이스 ID 유지 | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| 대문자 트레이스 ID | 예 | 예 |
| 버전 `ff` | 아니요 | 아니요 |
| 모두 0인 트레이스 ID | 아니요 | 아니요 |
| 모두 0인 부모 ID | 아니요 | 아니요 |

## 자주 묻는 질문

### 트레이스 ID는 무엇인가요?

트레이스 ID는 소문자 16진수 32자로 쓰는 16바이트 ID예요. 요청 1건이 거치는 모든 서비스에서 그 요청을 가리켜요. 서비스마다 `traceparent` 헤더로 넘겨요.

### 트레이스 ID와 스팬 ID는 무엇이 다른가요?

트레이스 ID는 요청 1건의 모든 서비스에서 같아요. 스팬 ID는 서비스 1개의 단계 1개를 가리켜요. 우리 요청에는 트레이스 ID 1개와 스팬 ID 3개가 있었어요.

### traceparent 헤더는 무엇인가요?

`traceparent`는 W3C Trace Context 권고안의 HTTP 헤더예요. 버전, 트레이스 ID, 호출한 쪽의 스팬 ID, 트레이스 플래그를 `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`처럼 담아요.

### traceparent 끝의 01은 무슨 뜻인가요?

`01`은 sampled 플래그가 켜졌다는 뜻이라, 호출한 쪽이 트레이스를 기록했을 수 있어요. `00`은 기록하지 않았다는 뜻이에요. LogBrew SDK 2개는 두 값을 모두 넘겼고, LogBrew는 트레이스를 보관했어요.

### 트레이스 ID가 같은 로그를 모두 찾으려면 어떻게 하나요?

`logbrew read logs --project "<project_id>" --trace <trace_id>`를 실행하거나, LogBrew 대시보드의 로그 검색창에 트레이스 ID를 붙여 넣으세요. 요청 중에 SDK가 쓰는 로그에는 모두 그 요청의 트레이스 ID가 붙어요.

### traceparent 헤더는 대소문자를 구분하나요?

네. 권고안은 소문자 16진수만 허용해요. LogBrew SDK 2개는 대문자 트레이스 ID를 받아 소문자로 바꿨지만, 엄격한 서비스는 헤더를 무시해요.

## 검색 1번으로 트레이스의 모든 로그 찾기

Node.js와 FastAPI용 LogBrew SDK는 `traceparent`를 읽고 보내며, 로그마다 요청의 트레이스 ID를 남겨요. 넉넉한 무료 요금제로 시작하세요. 카드 등록은 필요 없어요.

[무료로 시작](https://logbrew.co/ko)

## 출처

- [W3C Recommendation, Trace Context, 3.2 Traceparent Header](https://www.w3.org/TR/trace-context/#traceparent-header)
- [W3C Recommendation, Trace Context, 4.3 A traceparent is received](https://www.w3.org/TR/trace-context/#a-traceparent-is-received)
- [@logbrew/node on npm](https://www.npmjs.com/package/@logbrew/node)
- [LogBrewCo/sdk, logbrew-fastapi README](https://github.com/LogBrewCo/sdk/blob/main/python/logbrew_fastapi/README.md)

## 에이전트, Python, Node.js, React 가이드 더 보기

- [Claude Code와 Codex에 MCP 서버 추가하기](https://logbrew.co/ko/guides/mcp-server-claude-code-codex)
- [Claude Code와 Codex에서 AGENTS.md 쓰기](https://logbrew.co/ko/guides/agents-md)
- [Claude overloaded 529 오류와 rate limit 429 오류 해결하기](https://logbrew.co/ko/guides/claude-overloaded-rate-limit-error)
- [Python logging을 올바른 로그 레벨과 예외 기록까지 설정하기](https://logbrew.co/ko/guides/python-logging)
- [필드로 검색할 수 있는 로그 포맷과 로그 레벨로 구조화 로깅하기](https://logbrew.co/ko/guides/structured-logging)
- [Node.js 로깅을 Pino나 Winston으로 오류 하나 놓치지 않게 설정하기](https://logbrew.co/ko/guides/node-logging)
- [Django 로깅을 설정하고 모든 500 오류의 트레이스백 남기기](https://logbrew.co/ko/guides/django-logging)
- [FastAPI 로깅을 설정하고 트레이스백을 잃지 않고 오류 처리하기](https://logbrew.co/ko/guides/fastapi-logging)
- [React에 error boundary를 추가하고 놓치는 오류까지 기록하기](https://logbrew.co/ko/guides/react-error-boundary)
- [오류, 로그, 트레이스, 메트릭, 릴리스 가이드](https://logbrew.co/ko/guides)
