---
title: "Tracing · Ataris"
description: "The ataris CLI records each run as an ordered list of events across tool calls, context, processes, files, network, and policy decisions, then Ataris links every action to the cause that led to it."
canonical: "https://ataris.dev/product/tracing"
last-updated: 2026-10-10
---
# One timeline for everything an agent did.

The ataris CLI records each run as an ordered list of events across tool calls, context, processes, files, network, and policy decisions, then Ataris links every action to the cause that led to it.

## How a run becomes a timeline

1. **Captured from two sides.** Each tool call the agent makes is recorded with its result. Underneath, so is every process start, file open, and connection, on macOS and Linux, without root.
2. **Kept in order.** Every event gets a sequence number and a timestamp in microseconds, so the timeline shows things in the order they happened.
3. **Sorted by what it touched.** Events land in lanes, and each resource is marked normal, sensitive, or credential. A read of ~/.aws/credentials stands out from a read of src/index.ts.
4. **Linked to its cause.** Ataris ties each tool call to the processes it started, and a decision to the context that came before it.

## What the timeline shows

- **Every lane of the run.** Tool-call decisions, content entering the model's context, file activity, processes with their arguments, network connections, policy decisions, and session lifecycle, plus the skills the agent loaded and the MCP servers and tools it called.
- **Flags worth a second look.** Events are flagged for credential access, suspected prompt injection, outbound traffic, and sensitive data.
- **Causal links you can check.** Each link says how it was made: the process tree, a tool call, the model's context, or a heuristic with a confidence score.
- **Live or after the fact.** Watch a session in the dashboard as it runs, stream its events into your own code, or page through stored events later.

## Stream a run into your own tools

session.events() replays from the start, follows the session live, and resumes on its own after a dropped connection.

```ts
const session = await ataris.sessions.get(sessionId)

for await (const event of session.events()) {
  if (event.verdict === "blocked" || event.flags.includes("credential")) {
    console.warn("check this:", event.kind, event.summary)
  }
}
```

## Common questions

### How is this different from LLM observability?

LLM observability tracks prompts, completions, latency, and cost. Ataris also records what the agent did on the machine and the network, and links each action back to the context and decision behind it.

### Does the trace rely on what the agent reports?

No. Ataris records processes, files, and connections directly, not just the tool calls the agent reports, so a command's side effects are recorded even if the agent never mentions them.

### Are model calls recorded?

The CLI records the prompt that started the run, each decision to call a tool, and each result, but not the model's own text. Its calls to the model provider still appear as network events.

### What does a single event contain?

Its lane and kind, a one-line summary, the resource it touched, any policy verdict and flags, and an event-specific payload. Free text in a payload is capped at 4,096 characters.

## See a run end to end.

Book a demo and we'll walk through a traced run with your team.

[Book a demo](https://ataris.dev/contact) · [Read the docs](https://ataris.dev/docs/concepts/trace-events.md)