Tracing

:::caution Geplant – noch nicht verfügbar Diese Seite beschreibt Tracing-Funktionen, die in der öffentlichen API noch nicht implementiert sind. Aktuell steht die Request-Korrelation über die Response-Header request-id / correlation-id zur Verfügung, und Traces werden intern an unser Observability-Backend (OpenTelemetry) exportiert. Die unten gezeigten Trace-Abfrage-Endpoints (/api/v2/traces/*) veranschaulichen eine geplante Funktion und existieren noch nicht. :::

Die Tourfold-API unterstützt verteiltes Tracing, um Requests zu debuggen, Performance zu überwachen und den Datenfluss durch unsere Systeme nachzuvollziehen. Tracing macht die Ausführung von Anfragen über mehrere Dienste hinweg sichtbar.

Was ist Tracing?

Mit Tracing können Sie einen Request verfolgen, während er verschiedene Dienste und Komponenten durchläuft. Jeder Request erhält eine eindeutige Trace-ID, mit der Sie Logs, Metriken und Events über den gesamten Lebenszyklus eines Requests hinweg korrelieren können.

Funktionsweise des Tracings

Trace-Header

Jede API-Anfrage kann Tracing-Header enthalten:

curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Parent-Span-ID: span_111222333" \
     https://api.tourfold.com/api/v2/tours

Automatische Trace-Generierung

Geben Sie keine Tracing-Header an, generieren wir sie automatisch:

{
  "trace_id": "trace_123456789",
  "span_id": "span_987654321",
  "parent_span_id": null
}

Trace-Header

Header	Beschreibung	Pflicht
`X-Trace-ID`	Eindeutiger Bezeichner für den gesamten Trace	Ja
`X-Span-ID`	Eindeutiger Bezeichner für den aktuellen Span	Ja
`X-Parent-Span-ID`	ID des übergeordneten Spans (für verschachtelte Operationen)	Nein
`X-Sampled`	Ob dieser Trace gesampelt werden soll (true/false)	Nein

Tracing verwenden

Einfaches Tracing

# Beispiel: Anfrage mit Tracing-Headern
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Die Antwort-Header enthalten Trace-Informationen:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_987654321
# X-Request-ID: req_111222333

Verschachteltes Tracing

Für komplexe Operationen, die sich über mehrere API-Aufrufe erstrecken:

# Beispiel: Verschachteltes Tracing beim Erstellen einer Tour mit Stopps
# Erste Anfrage – Tour anlegen
curl -X POST https://api.tourfold.com/api/v2/tours \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_tour_001" \
  -H "X-Parent-Span-ID: span_main" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vienna City Tour",
    "description": "Explore the historic center of Vienna"
  }'

# Die Antwort enthält Trace-Header:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_tour_001

# Zweite Anfrage – Stopp zur Tour hinzufügen
curl -X POST https://api.tourfold.com/api/v2/tours/tour_123/stops \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_stop_001" \
  -H "X-Parent-Span-ID: span_tour_001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vienna Opera House",
    "location": {
      "latitude": 48.2038,
      "longitude": 16.3698
    }
  }'

Trace-Antwort-Header

API-Antworten enthalten Tracing-Informationen:

X-Trace-ID: trace_123456789
X-Span-ID: span_987654321
X-Request-ID: req_111222333

Traces einsehen

Trace-Dashboard

Greifen Sie über unser Trace-Dashboard auf Ihre Traces zu:

# Trace-Informationen abrufen
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

Beispiel für eine Trace-Antwort

{
  "trace_id": "trace_123456789",
  "spans": [
    {
      "span_id": "span_987654321",
      "parent_span_id": null,
      "operation_name": "GET /api/v2/tours",
      "start_time": "2024-01-15T10:30:00Z",
      "end_time": "2024-01-15T10:30:01Z",
      "duration_ms": 1000,
      "tags": {
        "http.method": "GET",
        "http.url": "/api/v2/tours",
        "http.status_code": 200
      }
    },
    {
      "span_id": "span_111222333",
      "parent_span_id": "span_987654321",
      "operation_name": "database.query",
      "start_time": "2024-01-15T10:30:00.100Z",
      "end_time": "2024-01-15T10:30:00.800Z",
      "duration_ms": 700,
      "tags": {
        "db.type": "postgresql",
        "db.statement": "SELECT * FROM tours"
      }
    }
  ],
  "total_duration_ms": 1000,
  "status": "completed"
}

Trace-Sampling

Sampling-Konfiguration

Steuern Sie das Trace-Sampling, um Kosten und Performance zu kontrollieren:

# Beispiel: Konditionales Tracing auf Basis von Sampling
# In stark frequentierten Szenarien nur 10 % der Requests tracen

# Request mit Tracing (10 % der Requests)
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Request ohne Tracing (90 % der Requests)
curl -H "X-Sampled: false" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

Adaptives Sampling

# Beispiel: Adaptives Sampling abhängig von der Fehlerrate
# Bei hoher Fehlerrate (>5 %) alle Requests tracen
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Bei mittlerer Fehlerrate (1–5 %) 50 % der Requests tracen
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Bei niedriger Fehlerrate (<1 %) 10 % der Requests tracen
curl -H "X-Sampled: false" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

Trace-Korrelation

Korrelation mit Logs

# Beispiel: Logs mit Traces korrelieren
# Bei API-Aufrufen Trace-Kontext im Log mitführen

# API-Anfrage
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Der Log-Eintrag sollte den Trace-Kontext enthalten:
# {
#   "timestamp": "2024-01-15T10:30:00Z",
#   "level": "INFO",
#   "message": "Making API request",
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321",
#   "url": "/api/v2/tours"
# }

Korrelation mit Metriken

# Beispiel: Metriken mit Traces korrelieren
# Metriken mit Trace-Kontext aufzeichnen

# API-Anfrage
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Metriken sollten den Trace-Kontext enthalten:
# {
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321",
#   "api_latency_ms": 150,
#   "database_queries": 3,
#   "timestamp": "2024-01-15T10:30:00Z"
# }

Debuggen mit Traces

Langsame Requests finden

# Beispiel: Trace-Performance analysieren
# Trace-Details abrufen und Performance auswerten

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

# Die Antwort enthält eine Performance-Analyse:
# {
#   "trace_id": "trace_123456789",
#   "total_duration": 2500,
#   "slow_spans": [
#     {
#       "operation": "database.query",
#       "duration": 1800
#     }
#   ],
#   "bottlenecks": [
#     {
#       "operation": "database.query",
#       "duration": 1800,
#       "percentage": "72.00"
#     }
#   ]
# }

Fehleranalyse

# Beispiel: Fehler in einem Trace analysieren
# Trace-Details abrufen und Fehler identifizieren

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

# Die Antwort enthält eine Fehleranalyse:
# {
#   "trace_id": "trace_123456789",
#   "errors": [
#     {
#       "operation": "database.query",
#       "error_message": "Connection timeout",
#       "duration": 5000
#     }
#   ]
# }

Performance-Monitoring

Trace-Metriken

# Beispiel: Trace-Metriken erfassen
# Trace-Performance über die Zeit überwachen

# Trace-Metriken abrufen
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/metrics

# Die Antwort enthält aggregierte Metriken:
# {
#   "total_traces": 1000,
#   "total_duration": 2500000,
#   "error_count": 25,
#   "slow_traces": 50,
#   "average_duration": 2500,
#   "error_rate": 0.025,
#   "slow_trace_rate": 0.05
# }

Best Practices

Trace-ID-Generierung

# Gut: Zeitstempel-basierte IDs mit UUID verwenden
# trace_1642233600000_a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Schlecht: Einfache Zufallszahlen verwenden
# trace_abc123def

Span-Verwaltung

# Beispiel: Spans in einer mehrstufigen Operation verwalten
# Span für die Tour-Erstellung starten
curl -X POST https://api.tourfold.com/api/v2/tours \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_tour_001" \
  -H "X-Parent-Span-ID: span_main" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Vienna City Tour"}'

# Child-Span für die Stopp-Erstellung starten
curl -X POST https://api.tourfold.com/api/v2/tours/tour_123/stops \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_stop_001" \
  -H "X-Parent-Span-ID: span_tour_001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vienna Opera House"}'

Trace-Propagation

# Beispiel: Trace-Kontext aus Antwort-Headern extrahieren
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Antwort-Header enthalten den Trace-Kontext:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_987654321

# Diese Werte in Folge-Requests übernehmen:
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours/tour_123/stops

Traces testen

Unit-Tests

# Beispiel: Propagation von Trace-Headern testen
# Eine Anfrage senden und prüfen, ob Trace-Header enthalten sind

curl -v -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Antwort enthält Trace-Header:
# < X-Trace-ID: trace_123456789
# < X-Span-ID: span_987654321

Integrationstests

# Beispiel: Trace-Korrelation mit Logs testen
# Eine Anfrage senden und Trace-Korrelation prüfen

# Request mit Trace-Kontext
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Logs enthalten den Trace-Kontext:
# {
#   "timestamp": "2024-01-15T10:30:00Z",
#   "level": "INFO",
#   "message": "Starting request",
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321"
# }

Nächste Schritte

Lernen Sie die Fehlerbehandlung kennen
Verstehen Sie das Rate Limiting

Was ist Tracing?​

Funktionsweise des Tracings​

Trace-Header​

Automatische Trace-Generierung​

Trace-Header​

Tracing verwenden​

Einfaches Tracing​

Verschachteltes Tracing​

Trace-Antwort-Header​

Traces einsehen​

Trace-Dashboard​

Beispiel für eine Trace-Antwort​

Trace-Sampling​

Sampling-Konfiguration​

Adaptives Sampling​

Trace-Korrelation​

Korrelation mit Logs​

Korrelation mit Metriken​

Debuggen mit Traces​

Langsame Requests finden​

Fehleranalyse​

Performance-Monitoring​

Trace-Metriken​

Best Practices​

Trace-ID-Generierung​

Span-Verwaltung​

Trace-Propagation​

Traces testen​

Unit-Tests​

Integrationstests​

Nächste Schritte​

Was ist Tracing?

Funktionsweise des Tracings

Trace-Header

Automatische Trace-Generierung

Trace-Header

Tracing verwenden

Einfaches Tracing

Verschachteltes Tracing

Trace-Antwort-Header

Traces einsehen

Trace-Dashboard

Beispiel für eine Trace-Antwort

Trace-Sampling

Sampling-Konfiguration

Adaptives Sampling

Trace-Korrelation

Korrelation mit Logs

Korrelation mit Metriken

Debuggen mit Traces

Langsame Requests finden

Fehleranalyse

Performance-Monitoring

Trace-Metriken

Best Practices

Trace-ID-Generierung

Span-Verwaltung

Trace-Propagation

Traces testen

Unit-Tests

Integrationstests

Nächste Schritte