How tracing works

Understand traces, observations, lifecycle events, and searchable context.

A trace is one complete agent run. The individual steps inside it are observations.

For example, one support request might produce a root agent observation, two model observations, and a tool observation. WeaveScope connects them into a tree so you can follow the run from start to finish.

Trace, debug, and monitor

The same observation data supports three workflows:

Workflow	Use it to answer
Trace	What happened during this run?
Debug	Which step failed, slowed down, or cost more than expected?
Monitor	How are many runs changing over time?

Tracing focuses on individual runs. Monitoring groups observations across a selected time range.

Build the trace tree

Each observation can include:

Field	Meaning
`trace_id`	Groups observations into one trace.
`observation_id` or `id`	Identifies one observation.
`parent_observation_id`	Attaches a child to its parent.
`name`	Human-readable operation name.
`kind`	Observation category, such as `agent`, `generation`, or `tool`.
`status`	Current lifecycle status.
`start_time` / `end_time`	Positions the observation in the waterfall.
`event_version`	Orders multiple updates to the same observation.

Parent and child IDs create the tree. Timestamps create the waterfall.

Observation kinds

Native ingestion accepts:

event, span, generation, agent, tool, chain, retriever, evaluator,
embedding, guardrail, graph, model, llm

WeaveScope groups related kinds in the interface. For example, model and llm observations appear as generation-style model calls.

Lifecycle events

Use these operations to update an observation:

Operation	Meaning
`start`	The operation started.
`finish`	The operation completed successfully.
`error`	The operation failed.

Accepted statuses are:

pending, running, success, ok, error, interrupted, cancelled

WeaveScope normalizes ok to success.

From ingestion to the trace list

WeaveScope validates and accepts trace data before processing it for display and analytics. A successful native ingestion request returns 202 Accepted once the accepted events are safely queued.

The trace list, trace details, and monitoring charts can update at slightly different times. After a new request is accepted, allow a brief processing delay before treating an empty search or chart as missing data.

Payloads and previews

Observations can include inputs, outputs, events, metadata, and errors. WeaveScope uses compact previews in lists and trees, then loads the complete payload when you open it.

Large values are collapsed initially so they do not overwhelm the trace view. Expand the payload when you need to inspect or copy the complete value.

Searchable context

Tracing filters can use:

Status and observation kind
Environment and release
Trace name
Provider and model
Tags
User ID
Flat custom fields

Add stable identifiers such as tenant_id, ticket_id, workflow_id, or account_id as custom fields when you expect to search or filter by them.

Use trace context consistently:

Field	Best use
`user_id`	Find one customer's runs.
`thread_id`	Connect turns in a conversation or durable workflow.
`session_id`	Connect a browser session, job, or short-lived process.
`environment`	Separate production, staging, development, and test traffic.
`release`	Compare behavior before and after a deployment.
`tags`	Add broad labels such as `rag`, `billing`, or `high_priority`.
`custom_fields`	Add flat, indexed identifiers and dimensions.
`metadata`	Add context that only needs to appear in trace details.

Keep large or nested values in metadata, inputs, outputs, or events rather than custom fields.

Running and interrupted traces

A trace remains running when WeaveScope receives a start event without a later finish or error event. This usually means the process stopped early, a short-lived VM exited before flushing, or a custom producer never sent the final event.

After a running trace remains inactive for the configured timeout, WeaveScope can present it as interrupted. A later update restores the genuine state and restarts the inactivity window if the trace is still running.