Spans

Contents

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.

LLM trace tree

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

PropertyDescription
$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_session_id

(Optional) Groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. A workload that finishes in a single trace does not need it. Send it as null to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id.
Example: session-abc-123, conv-user-456

$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"
}

Still have questions?

Was this page useful?