For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
  • Get started
    • Overview
    • Trace your first call
    • Run your first eval
    • Gateway & prompting
    • Live demo
  • Observability
      • Core concepts
      • Set up the SDK
      • Decorators (@workflow, @task)
      • Override span fields
      • Metadata & tags
      • Span types & multimodal
      • Manually log spans
      • OpenTelemetry (OTLP)
      • Retention & export
    • Users
  • Gateway
    • Limits
  • Admin
    • API keys
    • Provider keys
    • Workspaces & projects
    • Collaborate
  • Resources
  • Security & Support
    • Support
    • Status
LogoLogo
DiscordPlatform
On this page
  • What is tracing?
  • Spans
  • What’s in a span
  • Traces
  • Trace structure
  • Key trace fields
  • Multi-trace grouping
  • Threads
  • Key thread fields
ObservabilityTracing

Core concepts

Spans, traces, threads, and how Respan organizes your LLM data.
Was this page helpful?
Previous

Set up the SDK

Set up tracing with the Respan SDK for your LLM framework.
Next
Built with

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

CategoryWhat it storesKey fields
ContentWhat was sent and receivedinput, output, model, log_type
MetricsPerformance and cost datalatency, cost, usage, time_to_first_token
IdentityWho and whatcustomer_identifier, metadata, thread_identifier, group_identifier
TracingWhere in the workflowtrace_unique_id, span_parent_id, span_name
ConfigLLM settingstemperature, max_tokens, tools
StatusSuccess or failurestatus_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).