---
description: Understand traces, observations, lifecycle events, and searchable context.
---

# How tracing works

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](debug-traces.md) focuses on individual runs. [Monitoring](monitoring.md)
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:

```text
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:

```text
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.

{% hint style="info" %}
Use the ingestion response to confirm acceptance. Then search for the exact
trace ID in the project that owns the API key.
{% endhint %}

## 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.