---
title: "Trace ID vs span ID, décodés depuis un vrai en-tête traceparent"
description: "Un ID de trace (trace ID) désigne 1 requête dans chaque service qu’elle atteint, et il ne change pas. Un ID de span désigne 1 étape, donc chaque service en crée un."
canonical: "https://logbrew.co/fr/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace ID vs span ID, décodés depuis un vrai en-tête traceparent

Un ID de trace (trace ID) désigne 1 requête dans chaque service qu’elle atteint, et il ne change pas. Un ID de span désigne 1 étape, donc chaque service en crée un.

Testé le 21 novembre 2026 avec 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 et logbrew CLI 0.1.96

Par [Furkan Erday](https://github.com/furkanerday). Furkan Erday est le fondateur de LogBrew. Il développe LogBrew avec Claude Code et Codex tous les jours.

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

## Ce que chaque en-tête traceparent a fait à la trace

| En-tête envoyé par curl | ID de trace conservé | Les 2 logs partagent 1 ID de trace |
| --- | --- | --- |
| Valide, flags `01` | Oui | Oui |
| Valide, flags `00` | Oui | Oui |
| ID de trace en majuscules | Oui, en minuscules | Oui |
| ID de trace tout à zéro | Nouvelle trace | Oui |
| Version `ff` | Nouvelle trace | Oui |
| Aucun en-tête | Nouvelle trace | Oui |

6 requêtes vers un service Node.js qui appelle un service FastAPI, avec @logbrew/node 0.1.30 et logbrew-fastapi 0.1.14.

## Décoder l’en-tête traceparent

### Découper l’en-tête aux tirets

`traceparent` contient 4 champs en hexadécimal minuscule, séparés par `-`. Ce sont la version, l’ID de trace, l’ID parent et les flags de trace. Voici l’en-tête que curl a envoyé à notre service `checkout`.

Sortie

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

### Lire la version

`00` est la seule version de la Recommandation W3C Trace Context, et `ff` est invalide. Quand nous avons envoyé `ff`, les 2 SDK ont ignoré l’en-tête et démarré une nouvelle trace.

### Lire l’ID de trace

Les 32 caractères suivants sont l’ID de trace `9095c7b7bf222836f82c2c415bc2bd65`, 16 octets en hexadécimal. Il désigne toute la requête, et chaque service le transmet sans le modifier. Un ID de trace tout à zéro est invalide.

### Lire l’ID parent

Les 16 caractères suivants sont l’ID parent `fe8e70882fecdf07`, 8 octets en hexadécimal. C’est l’ID du span de l’appelant, donc il change à chaque saut. Un ID parent tout à zéro est invalide.

### Lire les flags de trace

Les 2 derniers caractères sont les flags, et seul le bit 0 a un sens. `01` indique que l’appelant a pu enregistrer la trace, et `00` qu’il ne l’a pas fait. Avec `00`, les 2 SDK ont quand même envoyé leurs spans, et LogBrew a affiché la trace.

## Transmettre la trace de Node.js à Python

### Installer les 2 SDK

Notre service `checkout` tourne sur Node.js avec `@logbrew/node`. Il appelle `payments`, une app FastAPI avec `logbrew-fastapi`. Utilisez dans chacun une clé serveur de votre projet LogBrew.

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

### Envelopper le serveur Node.js et son appel

`withLogBrewHttpHandler()` lit `traceparent` dans chaque requête et démarre un span. `fetchWithLogBrewSpan()` démarre un span enfant pour l’appel et écrit un nouveau `traceparent` avec l’ID de ce span. Le wrapper lit la clé dans `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");
```

### Ajouter LogBrew à l’app FastAPI

`init_logbrew()` lit `traceparent` dans chaque requête et démarre un span enfant. `logbrew.logging_handler` ajoute l’ID de trace et l’ID de span de la requête à chaque enregistrement de 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"}
```

## Trouver la trace d’une ligne de log

### Envoyer 1 requête à travers les 2 services

curl a envoyé un `traceparent`, comme peut le faire un navigateur ou une passerelle devant `checkout`. Sans l’en-tête, `checkout` démarre une nouvelle trace.

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

Sortie

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

### Comparer l’en-tête à chaque saut

Nous avons affiché l’en-tête dans chaque service. `checkout` a conservé l’ID de trace et mis l’ID de son span d’appel, `1a95bcb4e3fcb3ce`, dans l’ID parent. `payments` a lu cet en-tête et démarré en dessous le span `bc7e3f490d4a4d00`.

Sortie

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

### Trouver tous les logs de la trace

Copiez l’ID de trace depuis n’importe quelle ligne de log et passez-le à `--trace`. La CLI a renvoyé le log de chaque service. Dans le tableau de bord, collez l’ID de trace dans le champ de recherche de Logs.

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

Sortie

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

### Ouvrir la trace

La trace contient 3 spans, 2 de `checkout` et 1 de `payments`. Dans le tableau de bord, collez l’ID de trace dans le champ de recherche d’Explorer, puis ouvrez la trace.

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

Sortie

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

## Ce que nous avons vu pendant le test

Nous avons lancé `checkout` sur Node.js 22.18 avec @logbrew/node 0.1.30, et `payments` sur Python 3.13.9 avec FastAPI 0.165.0, uvicorn 0.54.0 et logbrew-fastapi 0.1.14. Les 2 envoyaient à un serveur LogBrew local. curl a envoyé 6 requêtes à `checkout`, 5 avec un `traceparent` différent et 1 sans.

Pour chaque requête, les logs des 2 services partageaient 1 ID de trace. Quand l’en-tête était valide, c’était l’ID de trace envoyé par curl. Quand l’en-tête était invalide ou absent, `checkout` a démarré une nouvelle trace et l’a transmise.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Requête vers `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Appel de `checkout` vers `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Requête vers `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

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

## Trace ID vs span ID

Un ID de trace fait 16 octets, écrits en 32 caractères hexadécimaux. Un ID de span fait 8 octets, écrits en 16. La spécification de l’API de trace OpenTelemetry ne déclare un ID valide que si au moins 1 octet n’est pas nul, et écrit les 2 en hexadécimal minuscule.

Dans OpenTelemetry, un contexte de span contient l’ID de trace, l’ID de span, les flags de trace et l’état de trace. `traceparent` porte les 3 premiers. L’en-tête `tracestate` porte l’état de trace, une liste d’au plus 32 entrées de fournisseurs. Aucun des 2 SDK LogBrew n’écrit `tracestate`.

|  | ID de trace | ID de span |
| --- | --- | --- |
| Caractères hexadécimaux | `32` | `16` |
| Identique à chaque saut | Oui | Non |
| Valide s’il est tout à zéro | Non | Non |

## Quand l’en-tête est faux

La Recommandation n’autorise que l’hexadécimal minuscule, et interdit la version `ff` et les ID tout à zéro. Un service qui reçoit un tel en-tête doit l’ignorer et démarrer une nouvelle trace. Les 2 SDK l’ont fait pour `ff` et pour un ID de trace ou un ID parent tout à zéro.

Les 2 SDK ont accepté un ID de trace en majuscules et l’ont transmis en minuscules. Envoyez des minuscules, car un service strict démarre une nouvelle trace à la place.

Sans en-tête, `checkout` a démarré une trace avec les flags `01`, et `payments` une avec `00`. LogBrew a conservé les 2 traces.

| ID de trace conservé | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| ID de trace en majuscules | Oui | Oui |
| Version `ff` | Non | Non |
| ID de trace tout à zéro | Non | Non |
| ID parent tout à zéro | Non | Non |

## Questions fréquentes

### Qu’est-ce qu’un trace ID ?

Un trace ID, ou ID de trace, est un ID de 16 octets écrit en 32 caractères hexadécimaux minuscules. Il désigne 1 requête dans chaque service qu’elle atteint. Chaque service le transmet dans l’en-tête `traceparent`.

### Quelle est la différence entre trace ID et span ID ?

L’ID de trace est le même dans chaque service d’une requête. Un ID de span désigne 1 étape dans 1 service. Notre requête a reçu 1 ID de trace et 3 ID de span.

### Qu’est-ce que l’en-tête traceparent ?

`traceparent` est l’en-tête HTTP de la Recommandation W3C Trace Context. Il contient la version, l’ID de trace, l’ID du span de l’appelant et les flags de trace, comme dans `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### Que signifie 01 à la fin de traceparent ?

`01` active le flag sampled, donc l’appelant a pu enregistrer la trace. `00` indique qu’il ne l’a pas fait. Les 2 SDK LogBrew ont transmis les 2 valeurs, et LogBrew a conservé la trace.

### Comment trouver tous les logs avec le même trace ID ?

Lancez `logbrew read logs --project "<project_id>" --trace <trace_id>`, ou collez l’ID de trace dans le champ de recherche de Logs du tableau de bord LogBrew. Chaque log écrit par les SDK pendant une requête porte l’ID de trace de cette requête.

### L’en-tête traceparent est-il sensible à la casse ?

Oui. La Recommandation n’autorise que l’hexadécimal minuscule. Les 2 SDK LogBrew ont accepté un ID de trace en majuscules et l’ont mis en minuscules, mais un service strict ignore l’en-tête.

## Trouvez tous les logs d’une trace en 1 recherche

Les SDK LogBrew pour Node.js et FastAPI lisent et envoient `traceparent`, et chaque log garde l’ID de trace de sa requête. Commencez avec le généreux forfait Free, sans carte bancaire.

[Commencer gratuitement](https://logbrew.co/fr)

## Sources

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

## Autres guides pour les agents, Python, Node.js et React

- [Ajouter un serveur MCP à Claude Code et Codex](https://logbrew.co/fr/guides/mcp-server-claude-code-codex)
- [Utiliser AGENTS.md dans Claude Code et Codex](https://logbrew.co/fr/guides/agents-md)
- [Corriger l’erreur Claude overloaded 529 et l’erreur rate limit 429](https://logbrew.co/fr/guides/claude-overloaded-rate-limit-error)
- [Configurer le module Python logging avec les bons niveaux de log et la capture des exceptions](https://logbrew.co/fr/guides/python-logging)
- [Structured logging avec un format de log et des niveaux que vous cherchez par champ](https://logbrew.co/fr/guides/structured-logging)
- [Configurer le logging Node.js avec Pino ou Winston sans perdre une seule erreur](https://logbrew.co/fr/guides/node-logging)
- [Configurez le logging Django et gardez la stack trace de chaque erreur 500](https://logbrew.co/fr/guides/django-logging)
- [Configurez le logging FastAPI et gérez les erreurs sans perdre la stack trace](https://logbrew.co/fr/guides/fastapi-logging)
- [Ajoutez un périmètre d’erreur React et loggez les erreurs qu’il laisse passer](https://logbrew.co/fr/guides/react-error-boundary)
- [Guides sur les erreurs, logs, traces, métriques et versions](https://logbrew.co/fr/guides)
