---
title: "Trace events · Ataris docs"
description: "Lanes, event kinds, verdicts, flags, resources, and causal links."
canonical: "https://ataris.dev/docs/concepts/trace-events"
last-updated: 2026-10-12
---
# Trace events

Lanes, event kinds, verdicts, flags, resources, and causal links.

A session's timeline is an ordered list of **trace events**. Each event is one thing that happened in the run: a tool call, a file open, a process start, a blocked command.

## Lanes

Every event belongs to a lane, which is how the dashboard groups the timeline:

| Lane | What it records |
| --- | --- |
| `model` | The agent's decisions to call a tool. |
| `context` | Content entering the model's context, such as a README the agent read or a tool's result. |
| `files` | File opens, reads, and writes. |
| `process` | Process starts and exits, with their arguments. |
| `network` | Outbound connections and HTTP requests. |
| `policy` | Policy decisions recorded against the action they governed. |
| `lifecycle` | Session start, stop, and other state changes. |

## Event fields

| Field | Description |
| --- | --- |
| `id` | Stream cursor. Use it to resume a stream or page through events. |
| `seq` | Order within the session. |
| `tsUs` | Timestamp in epoch microseconds. |
| `lane` | One of the lanes above. |
| `kind` | What happened, for example `process.exec`, `file.open`, `net.connect`, `http.request`, `context.ingest`, `decision.tool_use`. |
| `summary` | One line for the timeline, up to 200 characters. |
| `verdict` | `allowed`, `blocked`, or `alert`, when a policy applied. |
| `flags` | Any of `credential`, `injection`, `egress`, `sensitive`. |
| `resource` | What the event touched: `kind`, `key`, and `sensitivity`. |
| `pid`, `ppid` | Process ids, for process-level events. |
| `spanId`, `parentSpanId` | Span structure within the run. |
| `causedBySpanId`, `causeKind`, `causeConfidence` | The causal link, described below. |
| `payload` | Event-specific detail. Free text such as arguments or request bodies is capped at 4,096 characters. |

## Resources

`resource.kind` is one of `file`, `host`, `ip`, `credential`, `env`, `llm_endpoint`, or `binary`. `resource.sensitivity` is `normal`, `sensitive`, or `credential`, so a read of `~/.aws/credentials` stands out from a read of `src/index.ts`.

## Verdicts and flags

A **verdict** records what a [policy](/docs/concepts/policies) decided: `allowed`, `blocked`, or `alert`. **Flags** mark events worth a second look: a credential read, a suspected prompt injection, outbound traffic, or sensitive data.

## Causal links

Ataris links causes across the merged stream: for example, a tool call to the process it started. `causeKind` says how the link was made:

| `causeKind` | Meaning |
| --- | --- |
| `process_tree` | Parent and child processes. |
| `tool_use` | A model tool call and the action it caused. |
| `context` | Content in the model's context and the decision that followed. |
| `heuristic` | Inferred from timing and resources; `causeConfidence` says how sure. |

## Skills and MCP

Ataris lists the skills and MCP servers each run used, built from its events:

- **MCP servers and tools.** Claude Code names MCP tools `mcp__<server>__<tool>`. Each call is a `decision.tool_use` event with that name and the arguments it was called with, so the session page groups the calls by server and lists the tools used.
- **Skills.** A skill counts as used when the agent invokes it through the `Skill` tool, or reads its `SKILL.md`, as a `decision.tool_use` or a `file.open`. The session page lists each skill with how it was used, and the instructions it read.

Both are recorded by the [CLI](/docs/guides/cli).

## Reading events

Stream them live with `session.events()`, page through stored events with `ataris.sessions.events(id)`, or call the [REST API](/docs/reference/api) directly. See [Stream trace events](/docs/guides/stream-events).