> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inference.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Your Traces

Once traces are flowing into Catalyst, the next step is figuring out what they're telling you. The dashboard gives you two places to look: the **Traces** tab for browsing every span across your account, and the **Agents** tab for a per-agent view with overview, sessions, traces, and analysis. Halo is our open-source agent-loop optimizer, hosted right inside the Agents dashboard, that reads your traces and writes up what to improve.

This guide assumes you've already [captured your first trace](/get-started/capture-first-trace). If not, start there.

## Two places to look

<CardGroup cols={2}>
  <Card title="Traces tab" icon="route">
    Everything you've captured, across every service and agent. Filter by service, agent, time range, status, model, token usage, latency, errors, and custom span attributes. Open any trace to walk the tree.
  </Card>

  <Card title="Agents tab" icon="robot">
    A per-agent workspace. Pick an agent and you get four sub-tabs: Overview, Sessions, Traces, and Analysis.
  </Card>
</CardGroup>

## Inside the Agents tab

Click into any agent and you'll see four sub-tabs scoped to that agent.

| Sub-tab      | What it shows                                                                                                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview** | High-level metrics for the agent. Run counts, error rate, latency, token usage, and cost over time.                                                                                    |
| **Sessions** | One row per agent session. Click a session to see the full conversation, every tool call, and every span in order. This is where you go to understand "what happened in this one run." |
| **Traces**   | The same trace data as the global Traces tab, pre-filtered to this agent. Filter further by status, time range, model, or any span attribute.                                          |
| **Analysis** | The Halo workspace. Run Halo on the agent's traces, read past reports, and configure scheduled runs.                                                                                   |

<Tip>
  The Agents dashboard groups runs by `agent.id` and `agent.name` from your spans. If your agent runs aren't grouping the way you expect, see [Agent identity](/integrations/traces/agent-identity).
</Tip>

## Run Halo on your traces

[Halo](https://github.com/context-labs/halo) (Hierarchical Agent Loop Optimization) is an open-source RLM-based engine for analyzing agent traces and finding things to improve. It reads OpenTelemetry-compatible spans, decomposes them to find systemic failure modes across many runs, and writes up concrete fixes with citations back to specific traces.

You can run Halo two ways:

* **Self-hosted** from the [open-source repo](https://github.com/context-labs/halo). `pip install halo-engine`, point it at a JSONL trace file, and go.
* **Hosted** inside Catalyst. The Agents tab's Analysis sub-tab runs the same engine against the traces you've already collected, with no extra setup, no trace export, and no separate pipeline.

The hosted version is where most teams start. Open an agent, open Analysis, and either run Halo on demand or put it on a schedule.

### Run Halo on demand

<Steps>
  <Step title="Open the Analysis sub-tab">
    From the Agents tab, pick the agent you want to investigate and click **Analysis**.
  </Step>

  <Step title="Pick a trace window">
    Choose the time range Halo should review. Tighter windows give Halo more focused signal. A single problem agent over the last 24 hours beats a firehose of everything from the last month.
  </Step>

  <Step title="Write a prompt (or use the default)">
    The default prompt is the same one we use internally most of the time:

    <Metadata text="get-started/analyze-traces-default-prompt" />

    ```text theme={"system"}
    Analyze the traces in this window. Understand the agent's activity
    and identify anomalies, errors, inefficiencies, and opportunities
    to improve reliability, latency, cost, and tool usage. Highlight
    the top recurring failures, notable tool-call patterns, wasted or
    redundant work, slow or high-cost paths, and concrete fixes you'd
    recommend. Cite specific trace IDs for every key finding.
    ```

    You can also ask Halo anything specific: "Why is the refund agent timing out on Tuesdays?", "Which tool calls are returning empty results most often?", "Find redundant LLM calls in the planning loop."
  </Step>

  <Step title="Read the report">
    Halo returns a ranked list of findings with evidence pulled directly from your traces. Each finding cites the trace IDs it came from, so you can click straight from a finding into the trace tree that produced it.
  </Step>

  <Step title="Apply the changes and re-run">
    Update prompts, tools, or harness logic based on the findings. Capture a new window of traces, and run Halo again to confirm the issue is gone. This is the HALO loop: trace, analyze, fix, repeat.
  </Step>
</Steps>

### Schedule recurring runs

For agents you ship to production, the higher-leverage move is putting Halo on a schedule so it reviews recent traces automatically.

<Steps>
  <Step title="Open the schedule settings">
    From the Analysis sub-tab, open the schedules sheet and create a new schedule.
  </Step>

  <Step title="Pick a cadence and window">
    Hourly, daily, weekly, or monthly. The lookback window pre-fills to match the cadence (a daily schedule defaults to a 24-hour window) but you can override it. The runtime caps any single window at 30 days.
  </Step>

  <Step title="Set the prompt">
    The schedule prompt seeds from the same default shown above. Customize it per schedule when you want a recurring run focused on a specific failure mode.
  </Step>

  <Step title="Review reports as they land">
    Each scheduled run produces a new report in the Analysis history rail. Read the latest one, jump back to past reports to track regressions, and ignore runs where Halo finds nothing actionable.
  </Step>
</Steps>

## Inspect traces from the CLI

If you'd rather stay in the terminal, the [Inference CLI](/cli/overview) reads the same trace data the dashboard does.

<Metadata text="get-started/analyze-traces-cli" />

```bash theme={"system"}
# Browse recent traces
inf trace list --range 1h

# Open a trace tree or timeline
inf trace get <trace-id> --view tree
inf trace get <trace-id> --view timeline

# Search spans and inspect captured IO
inf span list --trace-id <trace-id> --kind LLM
inf span get <trace-id> <span-id> --view io
```

See [`inf trace`](/cli/traces) and [`inf span`](/cli/spans) for the full reference.

## Next steps

<CardGroup cols={2}>
  <Card title="Halo on GitHub" icon="github" href="https://github.com/context-labs/halo">
    The open-source HALO engine, methodology, and benchmarks. MIT licensed.
  </Card>

  <Card title="Set agent identity" icon="fingerprint" href="/integrations/traces/agent-identity">
    Add stable agent IDs so Halo and the Agents dashboard group runs correctly.
  </Card>

  <Card title="Capture more of your stack" icon="puzzle-piece" href="/integrations/traces/overview">
    Add tracing to your other providers, frameworks, and agent runtimes.
  </Card>

  <Card title="Wrap custom work" icon="pen-nib" href="/integrations/traces/manual-spans">
    Add spans around retrieval, routing, subprocesses, and unsupported SDKs.
  </Card>
</CardGroup>