Trace Explorer

Every call made through aiguard.chat() emits a TraceEvent. The Trace Explorer in the monitoring UI lets you browse, filter, and inspect those traces alongside their evaluation results.

Anatomy of a trace

json

{
  "trace_id": "01HMPV4S3X7QY2D5Z9K3WJ6B0E",
  "timestamp": "2026-04-12T09:31:11.402Z",
  "model": "gpt-4o",
  "input": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user",   "content": "Summarise PSD2 in two sentences." }
  ],
  "output": {
    "role": "assistant",
    "content": "PSD2 is an EU directive that ..."
  },
  "latency_ms": 612,
  "tokens": { "prompt": 38, "completion": 74, "total": 112 },
  "metadata": {
    "session_id": "u-1029",
    "feature":    "rag-search"
  },
  "evaluation": {
    "hallucination": { "score": 0.08, "passed": true },
    "adversarial":   { "score": 0.02, "passed": true }
  }
}

Filtering

The explorer supports filtering by model, time range, feature tag, score range, and evaluation outcome. Filters are URL-encoded so views can be shared.

Metadata you can attach

Pass arbitrary metadata when calling the SDK to make traces easier to find later. Common fields: session ID, feature flag, environment, request ID.

python

response = aiguard.chat(
    model="gpt-4o",
    messages=[...],
    metadata={
        "session_id": session.id,
        "feature":    "rag-search",
        "env":        "prod",
    },
)

Exporting traces

Use the monitoring API to export filtered traces as JSON for offline analysis or for building regression test cases.

bash

curl "http://localhost:8080/traces?model=gpt-4o&since=2026-04-01" > traces.json