Skip to main content

Core Observability Concepts

Arcane connects to trace backends that expose data in standard OpenTelemetry format. This page explains how execution data and journeys are captured and replayed: traces, spans, conversations, and events—and how they relate to each other in Arcane.

Traces​

A trace is an end-to-end execution of a request or workflow. Think of it as the full path a request takes through your system, from entry to exit.

What's in a trace:

  • A span tree (or graph) showing the ordering and timing of work
  • Spans — the individual timed steps inside the trace
  • Attributes on each span (status, service name, model/tool names, custom keys)
  • Events — optional timestamped logs or milestones attached to spans

Why it matters: Search and filters operate on trace and span attributes. Entity matching, highlights, and message reconstruction in Arcane all rely on the attributes your spans emit.

How you see it in Arcane: On the Traces page you pick a datasource, set a time range, search by query or attributes, then open a trace. The trace detail view shows the span tree, durations, errors, attributes, entity badges, highlights, and (for model spans) the reconstructed message thread.

Spans​

A span represents a single unit of work within a trace—for example, an HTTP request, a database call, or an LLM invocation. Spans have a start time, end time, and can have a parent span, forming a tree.

What's on a span:

  • Name — e.g. operation or service name
  • Start/end time — duration of the operation
  • Attributes — key-value pairs (status, service name, custom data)
  • Events — zero or more timestamped events that occurred during the span's lifetime

Why it matters: Entities in Arcane match spans by attributes (e.g. openinference.span.type = MODEL). When a span matches an entity, Arcane can show badges, highlights, and extract chat messages for conversations. See Entities for more.

How you see it in Arcane: Each node in the trace tree is a span. Click a span to see its attributes, highlights, and the Events tab—which shows all events attached to that span.

Events​

Events are timestamped records that belong to a span. In OpenTelemetry, a span can have an array of events; each event has a time, an optional name, and optional attributes. Events describe things that happened during the span's lifetime—for example, a log line, a checkpoint, or an exception.

How events relate to traces and spans in Arcane:

  • Trace → contains many spans
  • Span → can contain many events
  • Events are always attached to a span; they are not standalone. So: Trace → Spans → Events

What's in an event:

  • Timestamp — when the event occurred (within the span's time range)
  • Name — optional label (e.g. "exception", "message sent")
  • Attributes — optional key-value pairs with details

How you see it in Arcane:

  • In the Trace detail view, when you select a span, the Events tab shows all events for that span, ordered by time.
  • You can also view all events in the trace (from every span) in one timeline, ordered by timestamp. This helps you see the chronological sequence of events across the whole trace.
  • If a span (or trace) has no events, the Events tab shows an empty state.

Why it matters: Events give you a detailed, time-ordered view of what happened inside a span—useful for debugging, understanding LLM token streaming, or inspecting logs that are emitted as span events.

Conversations​

In Arcane, a conversation (sometimes called a session) is a group of traces that share one or more common attribute identifiers. You define which attributes identify a conversation; Arcane groups all traces that have the same value for any of those attributes and presents them as one replayable conversation.

How it's identified: You configure a conversation stitching configuration (Organisation Configuration → Conversation tab) with one or more Stitching Attribute Names—span attribute names used to group traces. The match is OR-based: if a trace has the same value as another trace for any of the listed attributes, they belong to the same conversation. For example, with two attributes in the configuration, all traces that share the same value for either attribute are grouped together.

What you configure in the UI (Organisation Configuration → Conversation tab):

  • Name — label for this conversation rule
  • Description — optional helper text for your team
  • Stitching Attribute Names — one or more span attribute names (e.g. gen_ai.conversation.id, session_id). Traces that have the same value for any of these attributes are grouped into one conversation.

Why it matters: You see the full user journey instead of isolated traces. It helps you debug context loss, tool choices, or model replies across services.

What you need to send: A consistent conversation identifier on every relevant span (the attribute names you configured). For model spans, you also need the message fields defined in your Entities message matching (canonical or flat) so Arcane can reconstruct readable chat content.

How it works: Traces that match the same conversation stitching configuration are grouped by attribute value, ordered by time, and rendered as one conversation. Message reconstruction (from Entities) supplies the readable chat content.

Summary: how it all fits together​

ConceptWhat it isRelationship in Arcane
TraceEnd-to-end executionContains many spans; root of the span tree
SpanOne timed unit of work in a traceBelongs to one trace; can have child spans; can have events
ConversationGroup of traces sharing attribute id(s)Defined by conversation stitching configuration (OR-based attributes); replayable journey
EventTimestamped record during a spanBelongs to one span; shown in Events tab / event timeline

Good practices​

  • Keep searches narrow in time to reduce noise and speed results.
  • Ensure spans carry the message fields consistently so conversations stay complete.
  • Emit span events for important checkpoints or logs so you can inspect them in the Events tab.

Learn more​