Spans

Spans are units of work within an LLM trace. These are events that represent individual operations and discrete durations within your LLM application, like function calls, vector searches, or data retrieval steps, providing granular visibility into the execution flow.

Spans are nested and displayed within a trace

PostHog captures spans to track atomic operations that make up your LLM workflow. For example:

Generations - LLM calls and interactions
Vector database searches - Document and embedding retrieval
Tool/function calls - API calls, calculations, database queries
RAG pipeline steps - Retrieval, reranking, context building
Data processing - Validation, chunking, formatting

For technical implementation details, see manual capture.

Event properties

A span is a single action within your application, such as a function call or vector database search.

Event name: $ai_span

Core properties

Property	Description
`$ai_trace_id`	The trace ID (a UUID to group related AI events together) Must contain only letters, numbers, and the following characters: `-`, `_`, `~`, `.`, `@`, `(`, `)`, `!`, `'`, `:`, `\|` Example: `d9222e05-8708-41b8-98ea-d4a21849e761`
`$ai_span_id`	(Optional) Unique identifier for this span Example: `bdf42359-9364-4db7-8958-c001f28c9255`
`$ai_span_name`	(Optional) The name of the span Example: `vector_search`, `data_retrieval`, `tool_call`
`$ai_parent_id`	(Optional) Parent ID for tree view grouping (`trace_id` or another `span_id`) Example: `537b7988-0186-494f-a313-77a5a8f7db26`
`$ai_input_state`	The input state of the span Example: `{"query": "search for documents about hedgehogs"}` or any JSON-serializable state
`$ai_output_state`	The output state of the span Example: `{"results": ["doc1", "doc2"], "count": 2}` or any JSON-serializable state
`$ai_latency`	(Optional) The latency of the span in seconds Example: `0.361`
`$ai_is_error`	(Optional) Boolean to indicate if the span encountered an error
`$ai_error`	(Optional) The error message or object if the span failed Example: `{"message": "Connection timeout", "code": "TIMEOUT"}`

Example API call

Terminal

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_span",
         "properties": {
             "distinct_id": "user_123",
             "$ai_trace_id": "d9222e05-8708-41b8-98ea-d4a21849e761",
             "$ai_input_state": {"query": "search for documents about hedgehogs", "filters": {"category": "animals"}},
             "$ai_output_state": {"results": [{"id": "doc_1", "content": "Hedgehogs are small mammals..."}, {"id": "doc_2", "content": "These nocturnal creatures..."}], "count": 2},
             "$ai_latency": 0.145,
             "$ai_span_name": "vector_search",
             "$ai_span_id": "bdf42359-9364-4db7-8958-c001f28c9255",
             "$ai_parent_id": "537b7988-0186-494f-a313-77a5a8f7db26",
             "$ai_is_error": false
         },
         "timestamp": "2025-01-30T12:00:00Z"
     }'

Event properties

Core properties

Example API call

Questions? Ask Max AI.

Community questions

Was this page useful?

Traces

Edwin Lim