---
title: "ID traccia vs ID span, decodificati da un vero header traceparent"
description: "L’ID traccia identifica 1 richiesta in ogni servizio che raggiunge e non cambia. L’ID span identifica 1 passaggio, quindi ogni servizio ne crea uno nuovo."
canonical: "https://logbrew.co/it/guides/trace-id"
last_updated: "2026-11-21"
---

# ID traccia vs ID span, decodificati da un vero header traceparent

L’ID traccia identifica 1 richiesta in ogni servizio che raggiunge e non cambia. L’ID span identifica 1 passaggio, quindi ogni servizio ne crea uno nuovo.

Testato il 21 novembre 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 e logbrew CLI 0.1.96

Di [Furkan Erday](https://github.com/furkanerday). Furkan Erday è il fondatore di LogBrew. Sviluppa LogBrew ogni giorno con Claude Code e Codex.

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

## Cosa ha fatto ogni header traceparent alla traccia

| Header inviato da curl | ID traccia mantenuto | I 2 log hanno lo stesso ID traccia |
| --- | --- | --- |
| Valido, flag `01` | Sì | Sì |
| Valido, flag `00` | Sì | Sì |
| ID traccia in maiuscolo | Sì, in minuscolo | Sì |
| ID traccia tutto a zero | Nuova traccia | Sì |
| Versione `ff` | Nuova traccia | Sì |
| Nessun header | Nuova traccia | Sì |

6 richieste a un servizio Node.js che chiama un servizio FastAPI, con @logbrew/node 0.1.30 e logbrew-fastapi 0.1.14.

## Decodifica l’header traceparent

### Dividi l’header ai trattini

`traceparent` contiene 4 campi in esadecimale minuscolo, separati da `-`. Sono la versione, l’ID traccia, l’ID padre e i flag della traccia. Questo è l’header che curl ha inviato al nostro servizio `checkout`.

Output

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

### Leggi la versione

`00` è l’unica versione della Raccomandazione W3C sul contesto della traccia, e `ff` non è valida. Quando abbiamo inviato `ff`, i 2 SDK hanno ignorato l’header e avviato una nuova traccia.

### Leggi l’ID traccia

I 32 caratteri successivi sono l’ID traccia `9095c7b7bf222836f82c2c415bc2bd65`, 16 byte in esadecimale. Identifica l’intera richiesta, e ogni servizio lo passa senza modifiche. Un ID traccia tutto a zero non è valido.

### Leggi l’ID padre

I 16 caratteri successivi sono l’ID padre `fe8e70882fecdf07`, 8 byte in esadecimale. È l’ID span del chiamante, quindi cambia a ogni passaggio tra servizi. Un ID padre tutto a zero non è valido.

### Leggi i flag della traccia

Gli ultimi 2 caratteri sono i flag, e solo il bit 0 ha un significato. `01` dice che il chiamante può aver registrato la traccia, `00` dice che non l’ha fatto. Anche con `00` i 2 SDK hanno inviato i loro span, e LogBrew ha mostrato la traccia.

## Passa la traccia da Node.js a Python

### Installa i 2 SDK

Il nostro servizio `checkout` gira su Node.js con `@logbrew/node`. Chiama `payments`, un’app FastAPI con `logbrew-fastapi`. In ciascuno usa una chiave server del tuo progetto LogBrew.

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

### Avvolgi il server Node.js e la sua chiamata

`withLogBrewHttpHandler()` legge `traceparent` da ogni richiesta e avvia uno span. `fetchWithLogBrewSpan()` avvia uno span figlio per la chiamata e scrive un nuovo `traceparent` con l’ID di quello span. Il wrapper legge la chiave da `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");
```

### Aggiungi LogBrew all’app FastAPI

`init_logbrew()` legge `traceparent` da ogni richiesta e avvia uno span figlio. `logbrew.logging_handler` aggiunge a ogni record di log l’ID traccia e l’ID span della richiesta.

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

## Trova la traccia di una riga di log

### Invia 1 richiesta attraverso i 2 servizi

curl ha inviato un `traceparent`, come può fare un browser o un gateway davanti a `checkout`. Senza l’header, `checkout` avvia una nuova traccia.

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

Output

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

### Confronta l’header a ogni passaggio

Abbiamo stampato l’header in ogni servizio. `checkout` ha mantenuto l’ID traccia e ha messo nell’ID padre l’ID del suo span di chiamata, `1a95bcb4e3fcb3ce`. `payments` ha letto quell’header e ha avviato sotto di esso lo span `bc7e3f490d4a4d00`.

Output

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

### Trova tutti i log della traccia

Copia l’ID traccia da una riga di log qualsiasi e passalo a `--trace`. La CLI ha restituito il log di ogni servizio. Nella dashboard, incolla l’ID traccia nella ricerca di Log.

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

Output

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

### Apri la traccia

La traccia contiene 3 span, 2 di `checkout` e 1 di `payments`. Nella dashboard, incolla l’ID traccia nella ricerca di Esplora, poi apri la traccia.

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

Output

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

## Cosa abbiamo visto nel test

Abbiamo eseguito `checkout` su Node.js 22.18 con @logbrew/node 0.1.30, e `payments` su Python 3.13.9 con FastAPI 0.165.0, uvicorn 0.54.0 e logbrew-fastapi 0.1.14. Entrambi inviavano a un server LogBrew locale. curl ha inviato 6 richieste a `checkout`, 5 con un `traceparent` diverso e 1 senza.

In ogni richiesta, i log dei 2 servizi avevano lo stesso ID traccia. Con un header valido, era l’ID traccia inviato da curl. Con un header non valido o assente, `checkout` ha avviato una nuova traccia e l’ha passata avanti.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Richiesta a `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Chiamata da `checkout` a `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Richiesta a `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

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

## ID traccia vs ID span

Un ID traccia è di 16 byte, scritti come 32 caratteri esadecimali. Un ID span è di 8 byte, scritti come 16. La specifica dell’API di tracing di OpenTelemetry considera valido un ID solo se almeno 1 byte non è zero, e scrive entrambi in esadecimale minuscolo.

In OpenTelemetry, uno span context contiene l’ID traccia, l’ID span, i flag della traccia e lo stato della traccia. `traceparent` porta i primi 3. L’header `tracestate` porta lo stato della traccia, un elenco di al massimo 32 voci dei fornitori. Nessuno dei 2 SDK di LogBrew scrive `tracestate`.

|  | ID traccia | ID span |
| --- | --- | --- |
| Caratteri esadecimali | `32` | `16` |
| Uguale a ogni passaggio | Sì | No |
| Valido se tutto a zero | No | No |

## Quando l’header è sbagliato

La Raccomandazione ammette solo esadecimale minuscolo e vieta la versione `ff` e gli ID tutti a zero. Un servizio che riceve un header così deve ignorarlo e avviare una nuova traccia. I 2 SDK l’hanno fatto con `ff` e con un ID traccia o un ID padre tutto a zero.

I 2 SDK hanno accettato un ID traccia in maiuscolo e l’hanno passato in minuscolo. Invia il minuscolo, perché un servizio rigoroso avvia invece una nuova traccia.

Senza header, `checkout` ha avviato una traccia con i flag `01`, e `payments` una con `00`. LogBrew ha conservato entrambe le tracce.

| ID traccia mantenuto | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| ID traccia in maiuscolo | Sì | Sì |
| Versione `ff` | No | No |
| ID traccia tutto a zero | No | No |
| ID padre tutto a zero | No | No |

## Domande frequenti

### Che cos’è un ID traccia?

Un ID traccia è un ID di 16 byte scritto come 32 caratteri esadecimali minuscoli. Identifica 1 richiesta in ogni servizio che la richiesta raggiunge. Ogni servizio lo passa nell’header `traceparent`.

### Qual è la differenza tra ID traccia e ID span?

L’ID traccia è lo stesso in ogni servizio di 1 richiesta. Un ID span identifica 1 passaggio in 1 servizio. La nostra richiesta ha avuto 1 ID traccia e 3 ID span.

### Che cos’è l’header traceparent?

`traceparent` è l’header HTTP della Raccomandazione W3C sul contesto della traccia. Contiene la versione, l’ID traccia, l’ID span del chiamante e i flag della traccia, come in `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### Cosa significa 01 alla fine di traceparent?

`01` attiva il flag sampled, quindi il chiamante può aver registrato la traccia. `00` dice che non l’ha fatto. I 2 SDK di LogBrew hanno passato entrambi i valori, e LogBrew ha conservato la traccia.

### Come trovo tutti i log con lo stesso ID traccia?

Esegui `logbrew read logs --project "<project_id>" --trace <trace_id>`, oppure incolla l’ID traccia nella ricerca di Log nella dashboard di LogBrew. Ogni log che gli SDK scrivono durante una richiesta porta l’ID traccia di quella richiesta.

### L’header traceparent distingue maiuscole e minuscole?

Sì. La Raccomandazione ammette solo esadecimale minuscolo. I 2 SDK di LogBrew hanno accettato un ID traccia in maiuscolo e l’hanno reso minuscolo, ma un servizio rigoroso ignora l’header.

## Trova tutti i log di una traccia con 1 ricerca

Gli SDK di LogBrew per Node.js e FastAPI leggono e inviano `traceparent`, e ogni log conserva l’ID traccia della sua richiesta. Inizia con il generoso piano gratuito, senza carta.

[Inizia gratis](https://logbrew.co/it)

## Fonti

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

## Altre guide per gli agenti, Python, Node.js e React

- [Aggiungi un server MCP a Claude Code e Codex](https://logbrew.co/it/guides/mcp-server-claude-code-codex)
- [Usa AGENTS.md in Claude Code e Codex](https://logbrew.co/it/guides/agents-md)
- [Risolvi l’errore overloaded 529 e l’errore di rate limit 429 di Claude](https://logbrew.co/it/guides/claude-overloaded-rate-limit-error)
- [Configura il modulo Python logging con i livelli di log giusti e la cattura delle eccezioni](https://logbrew.co/it/guides/python-logging)
- [Structured logging con un formato dei log e livelli che puoi cercare per campo](https://logbrew.co/it/guides/structured-logging)
- [Configura il logging in Node.js con Pino o Winston senza perdere nessun errore](https://logbrew.co/it/guides/node-logging)
- [Configura il logging di Django e conserva lo stack trace di ogni errore 500](https://logbrew.co/it/guides/django-logging)
- [Configura il logging di FastAPI e gestisci gli errori senza perdere lo stack trace](https://logbrew.co/it/guides/fastapi-logging)
- [Aggiungi un boundary di errore React e registra gli errori che si lascia sfuggire](https://logbrew.co/it/guides/react-error-boundary)
- [Guide su errori, log, tracce, metriche e release](https://logbrew.co/it/guides)
