---
title: "Trace ID vs span ID, decodificados de una cabecera traceparent real"
description: "El ID de traza (trace ID) nombra 1 solicitud en cada servicio que alcanza y no cambia. El ID de span nombra 1 paso, así que cada servicio crea uno nuevo."
canonical: "https://logbrew.co/es/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace ID vs span ID, decodificados de una cabecera traceparent real

El ID de traza (trace ID) nombra 1 solicitud en cada servicio que alcanza y no cambia. El ID de span nombra 1 paso, así que cada servicio crea uno nuevo.

Probado el 21 de noviembre de 2026 con 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 y logbrew CLI 0.1.96

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday es el fundador de LogBrew. Desarrolla LogBrew con Claude Code y Codex todos los días.

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

## Qué hizo cada cabecera traceparent con la traza

| Cabecera que envió curl | Mantuvo el ID de traza | Los 2 logs comparten 1 ID de traza |
| --- | --- | --- |
| Válida, flags `01` | Sí | Sí |
| Válida, flags `00` | Sí | Sí |
| ID de traza en mayúsculas | Sí, en minúsculas | Sí |
| ID de traza todo en ceros | Traza nueva | Sí |
| Versión `ff` | Traza nueva | Sí |
| Sin cabecera | Traza nueva | Sí |

6 solicitudes a un servicio Node.js que llama a un servicio FastAPI, con @logbrew/node 0.1.30 y logbrew-fastapi 0.1.14.

## Decodifica la cabecera traceparent

### Separa la cabecera por los guiones

`traceparent` tiene 4 campos en hexadecimal en minúsculas, separados por `-`. Son la versión, el ID de traza, el ID padre y los flags de traza. Esta es la cabecera que curl envió a nuestro servicio `checkout`.

Salida

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

### Lee la versión

`00` es la única versión de la Recomendación W3C Trace Context, y `ff` no es válida. Cuando enviamos `ff`, los 2 SDK ignoraron la cabecera y empezaron una traza nueva.

### Lee el ID de traza

Los 32 caracteres siguientes son el ID de traza `9095c7b7bf222836f82c2c415bc2bd65`, 16 bytes en hexadecimal. Nombra toda la solicitud, y cada servicio lo pasa sin cambios. Un ID de traza todo en ceros no es válido.

### Lee el ID padre

Los 16 caracteres siguientes son el ID padre `fe8e70882fecdf07`, 8 bytes en hexadecimal. Es el ID de span de quien llama, así que cambia en cada salto. Un ID padre todo en ceros no es válido.

### Lee los flags de traza

Los 2 últimos caracteres son los flags, y solo el bit 0 tiene significado. `01` dice que quien llama pudo registrar la traza, y `00` dice que no lo hizo. Con `00`, los 2 SDK enviaron igual sus spans, y LogBrew mostró la traza.

## Pasa la traza de Node.js a Python

### Instala los 2 SDK

Nuestro servicio `checkout` corre en Node.js con `@logbrew/node`. Llama a `payments`, una app FastAPI con `logbrew-fastapi`. Usa en cada uno una clave de servidor de tu proyecto de LogBrew.

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

### Envuelve el servidor Node.js y su llamada

`withLogBrewHttpHandler()` lee `traceparent` de cada solicitud y empieza un span. `fetchWithLogBrewSpan()` empieza un span hijo para la llamada y escribe un `traceparent` nuevo con el ID de ese span. El wrapper lee la clave 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");
```

### Añade LogBrew a la app FastAPI

`init_logbrew()` lee `traceparent` de cada solicitud y empieza un span hijo. `logbrew.logging_handler` añade a cada registro de log el ID de traza y el ID de span de la solicitud.

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

## Encuentra la traza de una línea de log

### Envía 1 solicitud a través de los 2 servicios

curl envió un `traceparent`, como puede hacerlo un navegador o un gateway delante de `checkout`. Sin la cabecera, `checkout` empieza una traza nueva.

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

Salida

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

### Compara la cabecera en cada salto

Imprimimos la cabecera en cada servicio. `checkout` mantuvo el ID de traza y puso en el ID padre el ID de su span de llamada, `1a95bcb4e3fcb3ce`. `payments` leyó esa cabecera y empezó debajo el span `bc7e3f490d4a4d00`.

Salida

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

### Encuentra todos los logs de la traza

Copia el ID de traza de cualquier línea de log y pásalo a `--trace`. La CLI devolvió el log de cada servicio. En el panel, pega el ID de traza en el buscador de Logs.

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

Salida

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

### Abre la traza

La traza tiene 3 spans, 2 de `checkout` y 1 de `payments`. En el panel, pega el ID de traza en el buscador de Explorar y abre la traza.

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

Salida

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

## Lo que vimos al probarlo

Ejecutamos `checkout` en Node.js 22.18 con @logbrew/node 0.1.30, y `payments` en Python 3.13.9 con FastAPI 0.165.0, uvicorn 0.54.0 y logbrew-fastapi 0.1.14. Los 2 enviaban a un servidor local de LogBrew. curl envió 6 solicitudes a `checkout`, 5 con un `traceparent` distinto y 1 sin él.

En cada solicitud, los logs de los 2 servicios compartieron 1 ID de traza. Cuando la cabecera era válida, era el ID de traza que envió curl. Cuando la cabecera no era válida o faltaba, `checkout` empezó una traza nueva y la pasó.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Solicitud a `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Llamada de `checkout` a `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Solicitud a `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

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

## Trace ID vs span ID

Un ID de traza tiene 16 bytes, escritos como 32 caracteres hexadecimales. Un ID de span tiene 8 bytes, escritos como 16. La especificación de la API de trazas de OpenTelemetry considera válido un ID solo si al menos 1 byte no es cero, y escribe los 2 en hexadecimal en minúsculas.

En OpenTelemetry, un contexto de span tiene el ID de traza, el ID de span, los flags de traza y el estado de traza. `traceparent` lleva los 3 primeros. La cabecera `tracestate` lleva el estado de traza, una lista de hasta 32 entradas de proveedores. Ninguno de los 2 SDK de LogBrew escribe `tracestate`.

|  | ID de traza | ID de span |
| --- | --- | --- |
| Caracteres hexadecimales | `32` | `16` |
| Igual en cada salto | Sí | No |
| Válido si es todo ceros | No | No |

## Cuando la cabecera está mal

La Recomendación solo permite hexadecimal en minúsculas, y prohíbe la versión `ff` y los ID todo en ceros. Un servicio que recibe una cabecera así debe ignorarla y empezar una traza nueva. Los 2 SDK lo hicieron con `ff` y con un ID de traza o un ID padre todo en ceros.

Los 2 SDK aceptaron un ID de traza en mayúsculas y lo pasaron en minúsculas. Envía minúsculas, porque un servicio estricto empieza una traza nueva en su lugar.

Sin cabecera, `checkout` empezó una traza con los flags `01`, y `payments` una con `00`. LogBrew guardó las 2 trazas.

| Mantuvo el ID de traza | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| ID de traza en mayúsculas | Sí | Sí |
| Versión `ff` | No | No |
| ID de traza todo en ceros | No | No |
| ID padre todo en ceros | No | No |

## Preguntas frecuentes

### ¿Qué es un trace ID?

Un trace ID, o ID de traza, es un ID de 16 bytes escrito como 32 caracteres hexadecimales en minúsculas. Nombra 1 solicitud en cada servicio al que llega. Cada servicio lo pasa en la cabecera `traceparent`.

### ¿Qué diferencia hay entre trace ID y span ID?

El ID de traza es el mismo en todos los servicios de 1 solicitud. Un ID de span nombra 1 paso en 1 servicio. Nuestra solicitud tuvo 1 ID de traza y 3 ID de span.

### ¿Qué es la cabecera traceparent?

`traceparent` es la cabecera HTTP de la Recomendación W3C Trace Context. Tiene la versión, el ID de traza, el ID de span de quien llama y los flags de traza, como en `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### ¿Qué significa el 01 al final de traceparent?

`01` activa el flag sampled, así que quien llama pudo registrar la traza. `00` dice que no lo hizo. Los 2 SDK de LogBrew pasaron los 2 valores, y LogBrew guardó la traza.

### ¿Cómo encuentro todos los logs con el mismo trace ID?

Ejecuta `logbrew read logs --project "<project_id>" --trace <trace_id>`, o pega el ID de traza en el buscador de Logs del panel de LogBrew. Cada log que los SDK escriben durante una solicitud lleva el ID de traza de esa solicitud.

### ¿La cabecera traceparent distingue mayúsculas y minúsculas?

Sí. La Recomendación solo permite hexadecimal en minúsculas. Los 2 SDK de LogBrew aceptaron un ID de traza en mayúsculas y lo pasaron a minúsculas, pero un servicio estricto ignora la cabecera.

## Encuentra todos los logs de una traza con 1 búsqueda

Los SDK de LogBrew para Node.js y FastAPI leen y envían `traceparent`, y cada log guarda el ID de traza de su solicitud. Empieza con el generoso plan gratuito, sin tarjeta.

[Empezar gratis](https://logbrew.co/es)

## Fuentes

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

## Más guías para agentes, Python, Node.js y React

- [Añade un servidor MCP a Claude Code y Codex](https://logbrew.co/es/guides/mcp-server-claude-code-codex)
- [Usa AGENTS.md en Claude Code y Codex](https://logbrew.co/es/guides/agents-md)
- [Soluciona el error 529 overloaded y el error 429 de rate limit en Claude](https://logbrew.co/es/guides/claude-overloaded-rate-limit-error)
- [Configura el módulo Python logging con los niveles de log correctos y captura de excepciones](https://logbrew.co/es/guides/python-logging)
- [Structured logging con un formato de log y niveles que puedes buscar por campo](https://logbrew.co/es/guides/structured-logging)
- [Configura el logging en Node.js con Pino o Winston sin perder ningún error](https://logbrew.co/es/guides/node-logging)
- [Configura el logging de Django y conserva la traza de pila de cada error 500](https://logbrew.co/es/guides/django-logging)
- [Configura el logging de FastAPI y maneja los errores sin perder la traza de pila](https://logbrew.co/es/guides/fastapi-logging)
- [Añade un error boundary de React y registra los errores que se le escapan](https://logbrew.co/es/guides/react-error-boundary)
- [Guías de errores, logs, trazas, métricas y versiones](https://logbrew.co/es/guides)
