Traces

Traces are a collection of generations and spans that capture a full interaction between a user and an LLM. The traces tab lists them along with the properties autocaptured by PostHog like the person, total cost, total latency, and more.

Trace timeline

Clicking on a trace opens a timeline of the interaction with all the generation and span events. The trace timeline enables you to see the entire conversation, profiling details, and the individual generations and spans.

AI event hierarchy

Traces consist of the following event hierarchy:

1. A trace is the top-level event entity.
2. A trace can contain multiple spans and generations.
3. A span can be the parent of other spans.
4. A generation can be the child of a span or trace.

Event properties

A trace is a group that contains multiple spans, generations, and embeddings. Traces can be manually sent as events or appear as pseudo-events automatically created from child events.

Event name: $ai_trace

Core properties

Pseudo-trace Events

When you send generation ($ai_generation), span ($ai_span), or embedding ($ai_embedding) events with a $ai_trace_id, PostHog automatically creates a pseudo-trace event that appears in the dashboard as a parent grouping. These pseudo-traces:

• Are not actual events in your data
• Automatically aggregate metrics from child events (latency, tokens, costs)
• Provide a hierarchical view of your AI operations
• Do not require sending an explicit $ai_trace event

This means you can either:

1. Send explicit $ai_trace events to control the trace metadata
2. Let PostHog automatically create pseudo-traces from your generation/span events

Example API call

curl -X POST "https://us.i.posthog.com/i/v0/e/" \
     -H "Content-Type: application/json" \
     -d '{
         "api_key": "<ph_project_api_key>",
         "event": "$ai_trace",
         "properties": {
             "distinct_id": "user_123",
             "$ai_trace_id": "d9222e05-8708-41b8-98ea-d4a21849e761",
             "$ai_input_state": [{"role": "user", "content": "Tell me a fun fact about hedgehogs"}],
             "$ai_output_state": [{"role": "assistant", "content": "Hedgehogs are small mammals with spines on their back."}],
             "$ai_latency": 1.23,
             "$ai_span_name": "hedgehog_facts_chat",
             "$ai_is_error": false
         },
         "timestamp": "2025-01-30T12:00:00Z"
     }'