Tracing
Preserve trace IDs, request group IDs and runtime context so AI traffic can be debugged from application logs to Kadryn.
Tracing connects an AI request in your application to the matching Kadryn event.
Use tracing when you need to debug production behavior, investigate cost spikes, correlate provider errors or support a customer incident.
Core identifiers
| Identifier | Purpose |
|---|---|
traceparent | Standard distributed tracing context. |
traceId | Trace identifier used in logs and search. |
X-Kadryn-Request-Group-Id | Groups several AI calls into one business operation. |
| Kadryn request ID | Identifies the exact Kadryn event. |
| Provider request ID | Identifies the upstream provider event when available. |
Idempotency-Key | Identifies a retry-safe logical operation. |
Gateway tracing
Send tracing headers with 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."
}
]
}'
Direct ingest tracing
Include trace fields in usage events:
{
"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
Use request group IDs for business operations that include multiple AI calls.
Examples:
invoice-run-2026-07-06-001
support-case-8412-resolution
nightly-report-2026-07-06
agent-session-0f3c
A request group ID should stay stable across all related calls.
What to log in your app
Safe log fields:
{
"service": "billing-api",
"project": "billing-api",
"feature": "invoice-assistant",
"environment": "prod",
"requestGroupId": "invoice-run-2026-07-06-001",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"kadrynRequestId": "req_..."
}
Do not log API keys, provider keys, Authorization headers or sensitive prompt payloads.
Debug workflow
- Find the application log line.
- Copy the trace ID or request group ID.
- Open Developers → Logs & Traces.
- Search by the same ID.
- Inspect status, model, provider, cost, latency and policy decisions.
- If needed, open Diagnostics to identify setup-level issues.
Troubleshooting
I cannot find the request
Check that the request passed through Gateway or direct ingest, and verify filters for environment, synthetic traffic and time range.
Multiple requests have the same trace
That can be valid. Use request group ID, span ID or Kadryn request ID to narrow the investigation.
Retries are hard to distinguish
Use idempotency keys and attempt counters in application logs.