Concepts | Respan Docs

What is tracing?

Everything in Respan starts with a span. A span is a single recorded unit of work: an LLM call, a tool execution, an agent step, or any operation you want to track. Every span captures its input, output, model, latency, cost, token usage, and metadata.

Spans are the building blocks for three views of your data:

Spans: the flat list of every recorded operation
Traces: spans grouped into a tree that shows how a workflow executed step by step
Threads: spans grouped into a conversation, ordered by time

All three views read from the same underlying span data. The difference is how they organize it.

For evaluation concepts (scores, evaluators, experiments), see Evals Concepts.

Spans

A span is a single recorded operation. When you send an LLM request through Respan, whether via the gateway, the API, or a tracing SDK, Respan creates a span.

Every span uses a universal input / output design. The system automatically serializes your data regardless of format, extracts type-specific fields (tool calls, thinking blocks, etc.), calculates metrics when possible, and associates the span with traces, threads, and customers based on the identifiers you provide.

What’s in a span

Category	What it stores	Key fields
Content	What was sent and received	`input`, `output`, `model`, `log_type`
Metrics	Performance and cost data	`latency`, `cost`, `usage`, `time_to_first_token`
Identity	Who and what	`customer_identifier`, `metadata`, `thread_identifier`, `group_identifier`
Tracing	Where in the workflow	`trace_unique_id`, `span_parent_id`, `span_name`
Config	LLM settings	`temperature`, `max_tokens`, `tools`
Status	Success or failure	`status_code`, `error_message`

Every span has a log_type that determines its input/output format. The most common is chat (messages in, assistant message out), but Respan also supports embedding, speech, transcription, workflow, agent, and more. See Log types for the full list.

For the complete field reference, see Span fields & parameters.

Traces

A trace is a group of spans that belong to the same workflow. Spans within a trace form a tree using parent-child relationships, so you can see exactly how a request flowed through your agents, tasks, and tools.

Trace structure

Key trace fields

trace_unique_id: groups all spans in the same workflow
span_unique_id: individual span identifier
span_parent_id: creates the parent-child hierarchy
span_name: descriptive name for the operation
span_workflow_name: the nearest workflow this span belongs to

Multi-trace grouping

Complex workflows can span multiple traces using trace_group_identifier:

Threads

A thread is a group of spans organized as a conversation. Unlike traces (which show a tree of how work was executed), threads show a linear sequence of messages ordered by time. This is the natural view for chat applications and dialogue systems.

Key thread fields

thread_identifier: groups spans into the same conversation
Each message in the thread maps to a span, so the same data that appears in traces also appears in threads

Threads and traces can overlap. A single span can belong to both a trace (showing where it fits in the workflow) and a thread (showing where it fits in the conversation).