---
title: "Trace-ID vs. Span-ID, an einem echten traceparent-Header erklärt"
description: "Eine Trace-ID benennt 1 Anfrage in jedem Dienst, den sie erreicht, und bleibt gleich. Eine Span-ID benennt 1 Schritt, also erzeugt jeder Dienst eine neue."
canonical: "https://logbrew.co/de/guides/trace-id"
last_updated: "2026-11-21"
---

# Trace-ID vs. Span-ID, an einem echten traceparent-Header erklärt

Eine Trace-ID benennt 1 Anfrage in jedem Dienst, den sie erreicht, und bleibt gleich. Eine Span-ID benennt 1 Schritt, also erzeugt jeder Dienst eine neue.

Getestet am 21. November 2026 mit 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 und logbrew CLI 0.1.96

Von [Furkan Erday](https://github.com/furkanerday). Furkan Erday hat LogBrew gegründet. Er entwickelt LogBrew jeden Tag mit Claude Code und Codex.

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

## Was jeder traceparent-Header mit dem Trace machte

| Header von curl | Trace-ID blieb gleich | Beide Logs teilen 1 Trace-ID |
| --- | --- | --- |
| Gültig, Flags `01` | Ja | Ja |
| Gültig, Flags `00` | Ja | Ja |
| Trace-ID in Großbuchstaben | Ja, in Kleinbuchstaben | Ja |
| Trace-ID nur aus Nullen | Neuer Trace | Ja |
| Version `ff` | Neuer Trace | Ja |
| Kein Header | Neuer Trace | Ja |

6 Anfragen an einen Node.js-Dienst, der einen FastAPI-Dienst aufruft, mit @logbrew/node 0.1.30 und logbrew-fastapi 0.1.14.

## Den traceparent-Header entschlüsseln

### Den Header an den Bindestrichen trennen

`traceparent` enthält 4 Felder in kleingeschriebenem Hex, getrennt durch `-`. Das sind Version, Trace-ID, Parent-ID und Trace-Flags. Diesen Header schickte curl an unseren Dienst `checkout`.

Ausgabe

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

### Die Version lesen

`00` ist die einzige Version in der W3C-Empfehlung Trace Context, und `ff` ist ungültig. Als wir `ff` schickten, ignorierten beide SDKs den Header und starteten einen neuen Trace.

### Die Trace-ID lesen

Die nächsten 32 Zeichen sind die Trace-ID `9095c7b7bf222836f82c2c415bc2bd65`, 16 Bytes in Hex. Die Trace-ID benennt die ganze Anfrage, und jeder Dienst gibt sie unverändert weiter. Eine Trace-ID nur aus Nullen ist ungültig.

### Die Parent-ID lesen

Die nächsten 16 Zeichen sind die Parent-ID `fe8e70882fecdf07`, 8 Bytes in Hex. Die Parent-ID ist die Span-ID des Aufrufers, darum ändert sie sich bei jedem Hop. Eine Parent-ID nur aus Nullen ist ungültig.

### Die Trace-Flags lesen

Die letzten 2 Zeichen sind die Flags, und nur Bit 0 hat eine Bedeutung. `01` sagt, dass der Aufrufer den Trace aufgezeichnet haben kann, `00` sagt, dass er es nicht tat. Auch mit `00` schickten beide SDKs ihre Spans, und LogBrew zeigte den Trace.

## Den Trace von Node.js an Python weitergeben

### Die 2 SDKs installieren

Unser Dienst `checkout` läuft auf Node.js mit `@logbrew/node`. Er ruft `payments` auf, eine FastAPI-App mit `logbrew-fastapi`. Nutze in beiden einen Server-Key deines LogBrew-Projekts.

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

### Den Node.js-Server und seinen Aufruf umschließen

`withLogBrewHttpHandler()` liest `traceparent` aus jeder Anfrage und startet einen Span. `fetchWithLogBrewSpan()` startet einen Child-Span für den Aufruf und schreibt einen neuen `traceparent` mit der ID dieses Spans. Der Wrapper liest den Key aus `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");
```

### LogBrew zur FastAPI-App hinzufügen

`init_logbrew()` liest `traceparent` aus jeder Anfrage und startet einen Child-Span. `logbrew.logging_handler` fügt jedem Log-Eintrag die Trace-ID und die Span-ID der Anfrage hinzu.

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

## Den Trace zu einer Logzeile finden

### 1 Anfrage durch beide Dienste schicken

curl schickte einen `traceparent`, wie es ein Browser oder ein Gateway vor `checkout` tun kann. Ohne den Header startet `checkout` einen neuen Trace.

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

Ausgabe

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

### Den Header an jedem Hop vergleichen

Wir haben den Header in jedem Dienst ausgegeben. `checkout` behielt die Trace-ID und setzte die ID seines Aufruf-Spans, `1a95bcb4e3fcb3ce`, als Parent-ID ein. `payments` las diesen Header und startete darunter den Span `bc7e3f490d4a4d00`.

Ausgabe

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

### Jedes Log des Traces finden

Kopiere die Trace-ID aus einer beliebigen Logzeile und übergib sie an `--trace`. Die CLI gab das Log jedes Dienstes zurück. Im Dashboard fügst du die Trace-ID in das Suchfeld von Logs ein.

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

Ausgabe

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

### Den Trace öffnen

Der Trace enthält 3 Spans, 2 von `checkout` und 1 von `payments`. Im Dashboard fügst du die Trace-ID in das Suchfeld von Erkunden ein und öffnest dann den Trace.

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

Ausgabe

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

## Was wir beim Testen gesehen haben

Wir ließen `checkout` auf Node.js 22.18 mit @logbrew/node 0.1.30 laufen und `payments` auf Python 3.13.9 mit FastAPI 0.165.0, uvicorn 0.54.0 und logbrew-fastapi 0.1.14. Beide sendeten an einen lokalen LogBrew-Server. curl schickte 6 Anfragen an `checkout`, 5 mit je einem anderen `traceparent` und 1 ohne.

Bei jeder Anfrage teilten die Logs beider Dienste 1 Trace-ID. War der Header gültig, war es die Trace-ID von curl. War der Header ungültig oder fehlte er, startete `checkout` einen neuen Trace und gab ihn weiter.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| Anfrage an `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| Aufruf von `checkout` an `payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| Anfrage an `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

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

## Trace-ID vs. Span-ID

Eine Trace-ID hat 16 Bytes, geschrieben als 32 Hex-Zeichen. Eine Span-ID hat 8 Bytes, geschrieben als 16. Die OpenTelemetry-Spezifikation der Trace-API nennt eine ID nur gültig, wenn mindestens 1 Byte nicht null ist, und schreibt beide in kleingeschriebenem Hex.

In OpenTelemetry enthält ein Span-Kontext die Trace-ID, die Span-ID, die Trace-Flags und den Trace-State. `traceparent` trägt die ersten 3. Der Header `tracestate` trägt den Trace-State, eine Liste mit bis zu 32 Einträgen von Anbietern. Keins der beiden LogBrew-SDKs schreibt `tracestate`.

|  | Trace-ID | Span-ID |
| --- | --- | --- |
| Hex-Zeichen | `32` | `16` |
| Gleich an jedem Hop | Ja | Nein |
| Gültig, wenn nur Nullen | Nein | Nein |

## Wenn der Header falsch ist

Die Empfehlung erlaubt nur kleingeschriebenes Hex und verbietet die Version `ff` und IDs nur aus Nullen. Ein Dienst, der so einen Header bekommt, muss ihn ignorieren und einen neuen Trace starten. Beide SDKs taten das bei `ff` und bei einer Trace-ID oder Parent-ID nur aus Nullen.

Beide SDKs nahmen eine Trace-ID in Großbuchstaben an und gaben sie in Kleinbuchstaben weiter. Schicke Kleinbuchstaben, denn ein strenger Dienst startet stattdessen einen neuen Trace.

Ohne Header startete `checkout` einen Trace mit den Flags `01` und `payments` einen mit `00`. LogBrew behielt beide Traces.

| Trace-ID blieb gleich | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| Trace-ID in Großbuchstaben | Ja | Ja |
| Version `ff` | Nein | Nein |
| Trace-ID nur aus Nullen | Nein | Nein |
| Parent-ID nur aus Nullen | Nein | Nein |

## Häufige Fragen

### Was ist eine Trace-ID?

Eine Trace-ID ist eine 16-Byte-ID, geschrieben als 32 kleingeschriebene Hex-Zeichen. Die Trace-ID benennt 1 Anfrage in jedem Dienst, den die Anfrage erreicht. Jeder Dienst gibt sie im Header `traceparent` weiter.

### Was ist der Unterschied zwischen Trace-ID und Span-ID?

Die Trace-ID ist in jedem Dienst einer Anfrage gleich. Eine Span-ID benennt 1 Schritt in 1 Dienst. Unsere Anfrage bekam 1 Trace-ID und 3 Span-IDs.

### Was ist der traceparent-Header?

`traceparent` ist der HTTP-Header der W3C-Empfehlung Trace Context. Er enthält die Version, die Trace-ID, die Span-ID des Aufrufers und die Trace-Flags, etwa `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### Was bedeutet 01 am Ende von traceparent?

`01` setzt das Sampled-Flag, der Aufrufer kann den Trace also aufgezeichnet haben. `00` sagt, dass er es nicht tat. Beide LogBrew-SDKs gaben jeden der beiden Werte weiter, und LogBrew behielt den Trace.

### Wie finde ich alle Logs mit derselben Trace-ID?

Führe `logbrew read logs --project "<project_id>" --trace <trace_id>` aus oder füge die Trace-ID in das Suchfeld von Logs im LogBrew-Dashboard ein. Jedes Log, das die SDKs während einer Anfrage schreiben, trägt die Trace-ID dieser Anfrage.

### Unterscheidet der traceparent-Header Groß- und Kleinschreibung?

Ja. Die Empfehlung erlaubt nur kleingeschriebenes Hex. Beide LogBrew-SDKs nahmen eine Trace-ID in Großbuchstaben an und schrieben sie klein, aber ein strenger Dienst ignoriert den Header.

## Finde jedes Log eines Traces mit 1 Suche

Die LogBrew-SDKs für Node.js und FastAPI lesen und senden `traceparent`, und jedes Log behält die Trace-ID seiner Anfrage. Starte mit dem großzügigen kostenlosen Plan, ohne Kreditkarte.

[Kostenlos starten](https://logbrew.co/de)

## Quellen

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

## Weitere Anleitungen für Agenten, Python, Node.js und React

- [MCP-Server in Claude Code und Codex hinzufügen](https://logbrew.co/de/guides/mcp-server-claude-code-codex)
- [AGENTS.md in Claude Code und Codex nutzen](https://logbrew.co/de/guides/agents-md)
- [Claude-Fehler 529 overloaded und 429 Rate Limit beheben](https://logbrew.co/de/guides/claude-overloaded-rate-limit-error)
- [Python-Logging einrichten mit den richtigen Log-Leveln und Exception-Erfassung](https://logbrew.co/de/guides/python-logging)
- [Structured Logging mit Log-Format und Log-Leveln, die du nach Feld durchsuchst](https://logbrew.co/de/guides/structured-logging)
- [Node.js-Logging mit Pino oder Winston einrichten und keinen Fehler verlieren](https://logbrew.co/de/guides/node-logging)
- [Django-Logging einrichten und den Traceback jedes 500-Fehlers behalten](https://logbrew.co/de/guides/django-logging)
- [FastAPI-Logging einrichten und Fehler behandeln, ohne den Traceback zu verlieren](https://logbrew.co/de/guides/fastapi-logging)
- [Eine React Error Boundary bauen und die Fehler loggen, die sie verpasst](https://logbrew.co/de/guides/react-error-boundary)
- [Anleitungen zu Fehlern, Logs, Traces, Metriken und Releases](https://logbrew.co/de/guides)
