Request Tracing für Fehlersuche nutzen

Anwendungsbeispiele

Beispiel 1: Route gibt 502 zurück

"Mein Nextcloud unter cloud.example.com gibt 502 zurück"

1. Debug-Tab öffnen, Tracing aktivieren, Route speichern
2. Request an cloud.example.com senden
3. Im Debug-Tab erscheint:

   21:45:54  GET  /  502  10.8.0.3
   

4. Status 502 = Backend nicht erreichbar → Peer offline oder Port falsch

Beispiel 2: Redirect-Schleife

"Meine Route leitet endlos weiter"

1. Tracing aktivieren
2. Im Debug-Tab sieht man mehrere 302-Einträge:

   21:46:01  GET  /           302  10.8.0.3
   21:46:01  GET  /login      302  10.8.0.3
   21:46:01  GET  /           302  10.8.0.3
   

3. Redirect-Schleife zwischen / und /login → Auth-Konfiguration prüfen

Beispiel 3: Request kommt nicht an

"Meine Route antwortet nicht"

1. Tracing aktivieren
2. Request senden — kein Eintrag im Debug-Tab
3. Der Request erreicht die Route gar nicht → DNS-Problem oder Caddy-Config prüfen

API

Trace-Einträge abrufen

GET /api/v1/routes/:id/trace?limit=50&since=1774640938.708

Query-Parameter:

Response:

{
  "ok": true,
  "data": {
    "entries": [
      {
        "timestamp": "2026-03-27T21:45:54.741Z",
        "method": "GET",
        "uri": "/",
        "status": 302,
        "remote_ip": "54.36.233.20",
        "host": "nas.domaincaster.com",
        "user_agent": "Mozilla/5.0 ..."
      }
    ]
  }
}

Tracing aktivieren/deaktivieren

Über die bestehende Route-API:

# Tracing aktivieren
curl -X PUT /api/v1/routes/:id \
  -H "Content-Type: application/json" \
  -d '{"debug_enabled": true}'

# Tracing deaktivieren
curl -X PUT /api/v1/routes/:id \
  -H "Content-Type: application/json" \
  -d '{"debug_enabled": false}'

Einschränkungen

• Nur HTTP-Routen: L4/TCP-Routen unterstützen kein Tracing (caddy-trace ist ein HTTP-Handler)
• Keine Persistenz: Trace-Daten werden nur in der Caddy-Log-Datei gespeichert, nicht in der Datenbank
• Kein Export: Trace-Einträge können nicht als CSV/JSON exportiert werden
• Kein URI-Filter: Alle Requests an die Route werden getraced, kein selektives Tracing möglich
• Performance: Tracing erzeugt zusätzliche Log-Einträge — bei hochfrequentierten Routen sollte es nur temporär aktiviert werden

Technische Details

caddy-trace Plugin

Repository: github.com/greenpau/caddy-trace Handler-Name: trace (http.handlers.trace) Go-Modul: github.com/greenpau/caddy-trace

Handler-Config

{
  "handler": "trace",
  "tag": "route-{routeId}",
  "response_debug_enabled": true
}

• tag: Eindeutiger Identifier pro Route (route-1, route-2, etc.) — wird zum Filtern der Log-Einträge verwendet
• response_debug_enabled: Aktiviert Response-Logging (Status-Code, Response-Größe, Response-Headers)

Log-Pipeline

1. caddy-trace schreibt Zap-JSON nach stdout
2. Supervisord leitet Caddy-stdout via tee nach /data/caddy/caddy-stdout.log
3. Die Trace-API (GET /api/v1/routes/:id/trace) liest diese Datei
4. Einträge werden nach tag === "route-{id}" gefiltert
5. Incoming- und Outgoing-Einträge werden per request_id zusammengeführt

Log-Format (caddy-trace Output)

Incoming Request:

{
  "level": "debug",
  "time": "2026-03-27T21:45:54.741Z",
  "msg": "debugging request",
  "request_id": "f9c59915-9071-419a-8ca2-46a035bfa356",
  "direction": "incoming",
  "tag": "route-1",
  "method": "GET",
  "host": "nas.domaincaster.com",
  "uri": "/",
  "remote_addr": "54.36.233.20",
  "user_agent": "curl/8.17.0",
  "headers": { "Accept": "*/*" }
}

Outgoing Response:

{
  "level": "debug",
  "time": "2026-03-27T21:45:54.742Z",
  "msg": "debugging response",
  "request_id": "f9c59915-9071-419a-8ca2-46a035bfa356",
  "direction": "outgoing",
  "tag": "route-1",
  "status_code": 302,
  "response_size": 0,
  "response_headers": { "Location": ["/route-auth/login?..."] }
}

Datenbank

Migration Version 27 (add_debug_enabled) — erstellt am 2026-03-27.

Backup/Restore

debug_enabled wird bei Backup/Restore berücksichtigt. Trace-Daten (Log-Datei) werden nicht exportiert.

UI-Integration

• Create-Card: Toggle "Request Tracing" innerhalb von http-fields (bei L4 ausgeblendet)
• Edit-Modal: Eigener "Debug"-Tab mit Toggle + Trace-Log-Container
• Debug-Tab wird bei L4-Routen ausgeblendet
• Polling: Auto-Refresh alle 3 Sekunden wenn Debug-Tab aktiv
• Polling stoppt bei Tab-Wechsel oder Modal-Close
• Badge: Bernsteinfarbener "Debug"-Badge in der Routen-Liste