Tracing
Préserver les trace IDs, request group IDs et le contexte runtime pour debugger le trafic IA entre vos logs et Kadryn.
Tracing connects un AI request dans votre application à le matching Kadryn événement.
Utilisez tracing lorsque vous devez debug production behavior, investigate coût spikes, correlate provider erreurs ou support un client incident.
Identifiants principaux
| Identifier | Purpose |
|---|---|
traceparent | Standard distributed tracing context. |
traceId | Trace identifier used dans logs et search. |
X-Kadryn-Request-Group-Id | Regroupe plusieurs appels IA dans une même opération métier. |
| Kadryn request ID | Identifies le exact Kadryn événement. |
| Provider request ID | Identifies le amont provider événement lorsque available. |
Idempotency-Key | Identifie une opération logique retryable en sécurité. |
Tracing Gateway
Envoyez tracing headers avec Gateway requests:
curl "$KADRYN_GATEWAY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $KADRYN_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Kadryn-Project: billing-api" \
-H "X-Kadryn-Feature: invoice-assistant" \
-H "X-Kadryn-Environment: prod" \
-H "X-Kadryn-Request-Group-Id: invoice-run-2026-07-06-001" \
-H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
-d '{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "Summarize invoice status."
}
]
}'
Tracing ingestion directe
Incluez les champs de trace dans les événements d’usage :
{
"timestamp": "2026-07-06T12:00:00.000Z",
"provider": "openai",
"model": "gpt-4.1-mini",
"inputTokens": 1200,
"outputTokens": 300,
"costCents": "4",
"project": "billing-api",
"feature": "invoice-assistant",
"environment": "prod",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"requestGroupId": "invoice-run-2026-07-06-001"
}
Request group IDs
Utilisez les request group IDs pour les opérations métier qui incluent plusieurs appels IA.
Exemples :
invoice-run-2026-07-06-001
support-case-8412-resolution
nightly-report-2026-07-06
agent-session-0f3c
Un request group ID doit rester stable sur tous les appels liés.
Ce qu’il faut logger dans votre application
Safe log champs:
{
"service": "billing-api",
"project": "billing-api",
"feature": "invoice-assistant",
"environment": "prod",
"requestGroupId": "invoice-run-2026-07-06-001",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"kadrynRequestId": "req_..."
}
Ne logguez pas les clés API, les clés provider, les headers Authorization ou les payloads de prompt sensibles.
Workflow de debug
- Find le application log line.
- Copy le trace ID ou request group ID.
- Ouvrez Developers → Logs & Traces.
- Recherchez avec le même ID.
- Inspect statut, model, provider, coût, latence et policy decisions.
- Si nécessaire, ouvrez Diagnostics pour identifier les problèmes de setup.
Dépannage
I cannot find le request
Vérifiez que la requête est passée via Gateway ou l’ingestion directe, puis vérifiez les filtres d’environnement, de trafic synthétique et de période.
Plusieurs requêtes ont la même trace
That peut be valid. Utilisez request group ID, span ID ou Kadryn request ID à narrow le investigation.
Retries sont hard à distinguish
Utilisez idempotency clés et attempt compteers dans application logs.