Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

Traces show the hierarchy of work inside one run. Use this view when you need to understand what happened end-to-end — which sub-chain decided to call which tool, how long each step took, and where the request went wrong.

​
Span hierarchy

A trace is a tree of spans. Each span is one event the SDK reported: Spans are nested by parent_run_id. The first span (root) is the agent call itself. Each chain or tool nested inside gets its own span. Leaf spans are the LLM calls or tool invocations.

​
What you see per span

FieldMeaning
NameDecorator string from @chain("..."), @tool("..."), or the LangChain class name.
Typeagent, chain, tool, llm, or a custom event.
DurationWall-clock milliseconds between *_start and *_end.
Statussuccess, error, or in_progress.
Input / outputRaw payloads, rendered as text or JSON.
TokensPer-LLM-call token usage when the provider reports it.
CostDerived from token usage × the model’s per-1k-token rate.

​
Reading a trace

1

Open the run

From LLM Calls or Threads, click a row to open the trace detail.
2

Scan the tree for red

Failed spans are highlighted. Their parent chain typically captures the error message in the output.
3

Inspect the slow spans

Sort or eyeball the duration column. A single tool call dominating the duration usually points at the bottleneck.
4

Open the LLM call

Click any llm span to see the prompt, system message, and completion alongside token usage.

​
Comparing two runs

Observatory ships a comparison endpoint that surfaces side-by-side diffs of two runs. From the trace view, click Compare and pick a second run. Useful for:
  • Investigating a regression after a prompt change
  • Comparing the same input across two model versions
  • Diffing a passing dataset run against a failing one
POST /api/run/compare
{ "run_id_a": "...", "run_id_b": "..." }

​
Saved runs

A run is marked saved when an event with name saved is emitted for it. Saved runs persist beyond retention windows and surface in dataset workflows. 
from flowxobservatory import track_event

track_event("saved", run_id=ctx.run_id)
See Event reporting for the full list of custom events.

LLM Calls

The table view that links into trace detail.

Threads

Multi-turn views built on the same trace data.
Last modified on June 2, 2026