---
title: "Trace ID vs span ID, decodificados de um header traceparent real"
description: "O trace ID identifica 1 requisição em todo serviço que ela alcança e não muda. O span ID identifica 1 etapa, então cada serviço cria um novo."
canonical: "https://logbrew.co/pt-BR/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace ID vs span ID, decodificados de um header traceparent real

O trace ID identifica 1 requisição em todo serviço que ela alcança e não muda. O span ID identifica 1 etapa, então cada serviço cria um novo.

Testado em 21 de novembro de 2026 com 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 e logbrew CLI 0.1.96

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday é o fundador do LogBrew. Ele desenvolve o LogBrew com Claude Code e Codex todos os dias.

Canonical: https://logbrew.co/pt-BR/guides/trace-id

## O que cada header traceparent fez com o trace

| Header que o curl enviou | Manteve o trace ID | Os 2 logs têm o mesmo trace ID |
| --- | --- | --- |
| Válido, flags `01` | Sim | Sim |
| Válido, flags `00` | Sim | Sim |
| Trace ID em maiúsculas | Sim, em minúsculas | Sim |
| Trace ID só com zeros | Trace novo | Sim |
| Versão `ff` | Trace novo | Sim |
| Sem header | Trace novo | Sim |

6 requisições para um serviço Node.js que chama um serviço FastAPI, com @logbrew/node 0.1.30 e logbrew-fastapi 0.1.14.

## Decodifique o header traceparent

### Separe o header nos hifens

`traceparent` tem 4 campos em hexadecimal minúsculo, separados por `-`. São a versão, o trace ID, o parent ID e as flags do trace. Este é o header que o curl enviou para o nosso serviço `checkout`.

Saída

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

### Leia a versão

`00` é a única versão na Recomendação W3C Trace Context, e `ff` é inválida. Quando enviamos `ff`, os 2 SDKs ignoraram o header e iniciaram um trace novo.

### Leia o trace ID

Os próximos 32 caracteres são o trace ID `9095c7b7bf222836f82c2c415bc2bd65`, 16 bytes em hexadecimal. Ele identifica a requisição inteira, e cada serviço o repassa sem mudança. Um trace ID só com zeros é inválido.

### Leia o parent ID

Os próximos 16 caracteres são o parent ID `fe8e70882fecdf07`, 8 bytes em hexadecimal. Ele é o span ID do span de quem chamou, então muda a cada salto. Um parent ID só com zeros é inválido.

### Leia as flags do trace

Os 2 últimos caracteres são as flags, e só o bit 0 tem significado. `01` diz que quem chamou pode ter gravado o trace, e `00` diz que não gravou. Com `00`, os 2 SDKs enviaram os spans mesmo assim, e o LogBrew mostrou o trace.

## Passe o trace do Node.js para o Python

### Instale os 2 SDKs

Nosso serviço `checkout` roda em Node.js com `@logbrew/node`. Ele chama `payments`, um app FastAPI com `logbrew-fastapi`. Use em cada um uma chave de servidor do seu projeto LogBrew.

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

### Envolva o servidor Node.js e a chamada dele

`withLogBrewHttpHandler()` lê o `traceparent` de cada requisição e inicia um span. `fetchWithLogBrewSpan()` inicia um span filho para a chamada e escreve um `traceparent` novo com o ID desse span. O wrapper lê a chave de `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");
```

### Adicione o LogBrew ao app FastAPI

`init_logbrew()` lê o `traceparent` de cada requisição e inicia um span filho. `logbrew.logging_handler` adiciona o trace ID e o span ID da requisição a cada log.

```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"}
```

## Encontre o trace de uma linha de log

### Envie 1 requisição pelos 2 serviços

O curl enviou um `traceparent`, como um navegador ou um gateway na frente do `checkout` pode fazer. Sem o header, o `checkout` inicia um trace novo.

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

Saída

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

### Compare o header em cada salto

Imprimimos o header em cada serviço. O `checkout` manteve o trace ID e colocou o ID do span da chamada, `1a95bcb4e3fcb3ce`, no parent ID. O `payments` leu esse header e iniciou o span `bc7e3f490d4a4d00` abaixo dele.

Saída

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

### Encontre todos os logs do trace

Copie o trace ID de qualquer linha de log e passe para `--trace`. A CLI retornou o log de cada serviço. No painel, cole o trace ID na busca de Logs.

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

Saída

```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]
```

### Abra o trace

O trace tem 3 spans, 2 do `checkout` e 1 do `payments`. No painel, cole o trace ID na busca de Explorar e abra o trace.

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

Saída

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

## O que vimos no teste

Rodamos o `checkout` no Node.js 22.18 com @logbrew/node 0.1.30, e o `payments` no Python 3.13.9 com FastAPI 0.165.0, uvicorn 0.54.0 e logbrew-fastapi 0.1.14. Os 2 enviavam para um servidor LogBrew local. O curl enviou 6 requisições para o `checkout`, 5 com um `traceparent` diferente e 1 sem.

Em cada requisição, os logs dos 2 serviços tiveram o mesmo trace ID. Quando o header era válido, era o trace ID que o curl enviou. Quando o header era inválido ou não existia, o `checkout` iniciou um trace novo e o repassou.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Requisição ao `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Chamada do `checkout` ao `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Requisição ao `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

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

## Trace ID vs span ID

Um trace ID tem 16 bytes, escritos como 32 caracteres hexadecimais. Um span ID tem 8 bytes, escritos como 16. A especificação da API de trace do OpenTelemetry só considera um ID válido quando pelo menos 1 byte não é zero, e escreve os 2 em hexadecimal minúsculo.

No OpenTelemetry, um span context guarda o trace ID, o span ID, as flags do trace e o trace state. O `traceparent` leva os 3 primeiros. O header `tracestate` leva o trace state, uma lista de até 32 entradas de fornecedores. Nenhum dos 2 SDKs do LogBrew escreve `tracestate`.

|  | Trace ID | Span ID |
| --- | --- | --- |
| Caracteres hexadecimais | `32` | `16` |
| Igual em cada salto | Sim | Não |
| Válido só com zeros | Não | Não |

## Quando o header está errado

A Recomendação só permite hexadecimal minúsculo e proíbe a versão `ff` e IDs só com zeros. Um serviço que recebe um header assim deve ignorá-lo e iniciar um trace novo. Os 2 SDKs fizeram isso com `ff` e com um trace ID ou um parent ID só com zeros.

Os 2 SDKs aceitaram um trace ID em maiúsculas e o repassaram em minúsculas. Envie minúsculas, porque um serviço rigoroso inicia um trace novo no lugar.

Sem header, o `checkout` iniciou um trace com as flags `01`, e o `payments` um com `00`. O LogBrew guardou os 2 traces.

| Manteve o trace ID | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| Trace ID em maiúsculas | Sim | Sim |
| Versão `ff` | Não | Não |
| Trace ID só com zeros | Não | Não |
| Parent ID só com zeros | Não | Não |

## Perguntas frequentes

### O que é trace ID?

O trace ID é um ID de 16 bytes, escrito como 32 caracteres hexadecimais minúsculos. Ele identifica 1 requisição em todo serviço que ela alcança. Cada serviço o repassa no header `traceparent`.

### Qual a diferença entre trace ID e span ID?

O trace ID é o mesmo em todos os serviços de 1 requisição. Um span ID identifica 1 etapa em 1 serviço. Nossa requisição teve 1 trace ID e 3 span IDs.

### O que é o header traceparent?

`traceparent` é o header HTTP da Recomendação W3C Trace Context. Ele traz a versão, o trace ID, o span ID de quem chamou e as flags do trace, como em `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### O que significa o 01 no fim do traceparent?

`01` liga a flag sampled, então quem chamou pode ter gravado o trace. `00` diz que não gravou. Os 2 SDKs do LogBrew repassaram os 2 valores, e o LogBrew guardou o trace.

### Como encontro todos os logs com o mesmo trace ID?

Rode `logbrew read logs --project "<project_id>" --trace <trace_id>` ou cole o trace ID na busca de Logs do painel do LogBrew. Cada log que os SDKs escrevem durante uma requisição traz o trace ID dessa requisição.

### O header traceparent diferencia maiúsculas de minúsculas?

Sim. A Recomendação só permite hexadecimal minúsculo. Os 2 SDKs do LogBrew aceitaram um trace ID em maiúsculas e o passaram para minúsculas, mas um serviço rigoroso ignora o header.

## Encontre todos os logs de um trace com 1 busca

Os SDKs do LogBrew para Node.js e FastAPI leem e enviam `traceparent`, e cada log guarda o trace ID da requisição dele. Comece no plano gratuito generoso, sem cartão.

[Comece grátis](https://logbrew.co/pt-BR)

## Fontes

- [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)

## Mais guias para agentes, Python, Node.js e React

- [Adicione um servidor MCP ao Claude Code e ao Codex](https://logbrew.co/pt-BR/guides/mcp-server-claude-code-codex)
- [Use AGENTS.md no Claude Code e no Codex](https://logbrew.co/pt-BR/guides/agents-md)
- [Corrija o erro 529 overloaded e o erro 429 de rate limit do Claude](https://logbrew.co/pt-BR/guides/claude-overloaded-rate-limit-error)
- [Configure o Python logging com os níveis de log certos e captura de exceções](https://logbrew.co/pt-BR/guides/python-logging)
- [Structured logging com formato de log e níveis que você busca por campo](https://logbrew.co/pt-BR/guides/structured-logging)
- [Configure o logging em Node.js com Pino ou Winston sem perder nenhum erro](https://logbrew.co/pt-BR/guides/node-logging)
- [Configure o logging do Django e guarde o stack trace de cada erro 500](https://logbrew.co/pt-BR/guides/django-logging)
- [Configure o logging do FastAPI e trate os erros sem perder o stack trace](https://logbrew.co/pt-BR/guides/fastapi-logging)
- [Adicione um error boundary no React e registre os erros que ele deixa passar](https://logbrew.co/pt-BR/guides/react-error-boundary)
- [Guias de erros, logs, traces, métricas e versões](https://logbrew.co/pt-BR/guides)
