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

# Observability

> Events, sessions, metrics, schedules, QA, log feed, and brief — monitor everything happening in your Genie system

# Observability Commands

Genie provides seven command groups for observability: `events` for the audit log, `sessions` for Claude Code session history, `metrics` for machine state, `schedule` for cron triggers, `qa` for self-testing, `log` for a unified real-time feed, and `brief` for session startup context.

## Events

The `genie events` command group queries the PostgreSQL audit event log. Events are structured as OTel-compatible records covering API costs, tool usage, task transitions, and errors.

Thirteen subcommands group into three layers: **reading** (`list`, `errors`, `costs`, `tools`, `timeline`, `timeline-v2`, `summary`, `scan`), **streaming** (`stream`, `stream-follow`, `subscribe`), and **operations** (`migrate`, `admin`). Reading commands hit the table directly; streaming commands tail events in real time (with `stream-follow` and `subscribe` targeting the v2 enriched surface); operations commands are one-shot migrations and sentinel-audited incident response.

### `genie events list`

List recent audit events. Pass `--v2` to switch to the enriched `genie_runtime_events` surface with TraceId/SpanId/Severity/Duration columns.

```bash theme={"dark"}
genie events list [options]
```

| Option               | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `--type <type>`      | Filter by `event_type`                                                                    |
| `--entity <entity>`  | Filter by entity type or entity ID                                                        |
| `--since <duration>` | Time window, e.g., `1h`, `30m`, `2d` (default: `1h`)                                      |
| `--errors-only`      | Show only error events                                                                    |
| `--limit <n>`        | Max rows to return (default: `50`)                                                        |
| `--json`             | Output as JSON                                                                            |
| `-f, --follow`       | Follow mode — real-time streaming (alias: `genie events stream`)                          |
| `--v2`               | Use enriched `genie_runtime_events` surface with TraceId/SpanId/Severity/Duration columns |
| `--kind <prefix>`    | Filter v2 rows by kind/subject prefix (e.g., `mailbox`, `agent.lifecycle`)                |
| `--severity <level>` | Filter v2 rows by severity (`debug`\|`info`\|`warn`\|`error`\|`fatal`)                    |

```bash theme={"dark"}
genie events list --since 30m --errors-only
genie events list --v2 --kind agent.lifecycle --severity warn
```

<Note>
  `genie events list` defaults to the last hour. Widen with `--since 1d` or narrow with `--since 5m` when chasing a specific incident.
</Note>

<Tip>
  For a walkthrough of `rot.*` and `detector.*` events and triage, see [Detectors](/genie/observability/detectors).
</Tip>

### `genie events stream`

Stream audit + runtime events in real-time (tail -f style). Reach for this when you want a live firehose across both the legacy `audit_events` and the enriched `genie_runtime_events` surfaces — for example, while watching a wish execute or debugging a noisy agent.

```bash theme={"dark"}
genie events stream [options]
```

| Option              | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| `--type <type>`     | Filter by `event_type`                                                 |
| `--entity <entity>` | Filter by entity type or entity ID                                     |
| `--errors-only`     | Show only error events                                                 |
| `--kind <kind>`     | Filter runtime events by kind (`tool_call`, `message`, `prompt`, etc.) |
| `--agent <agent>`   | Filter runtime events by agent                                         |
| `--audit-only`      | Stream only `audit_events` (skip runtime)                              |
| `--runtime-only`    | Stream only runtime events (skip audit)                                |
| `--all`             | Show all events including noisy ones (`command_success`, etc.)         |
| `--json`            | Output as JSON                                                         |

```bash theme={"dark"}
genie events stream --runtime-only --kind tool_call
genie events stream --errors-only --agent engineer-1
```

### `genie events stream-follow`

Follow-stream enriched `genie_runtime_events` via PostgreSQL `LISTEN/NOTIFY` with an id-cursor for resumable consumption (v2). Unlike `stream`, this command is built for long-running sidecars that need to survive reconnects — pass `--consumer-id` and it picks up where it left off.

The `--kind` flag accepts `*` globs for subject-tree subscriptions. For example, `--kind 'detector.*'` follows every event emitted by the detector subsystem. See [Detectors](./observability/detectors.mdx) for the catalog of kinds (sibling PR — page lands alongside this one).

```bash theme={"dark"}
genie events stream-follow [options]
```

| Option               | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| `--follow`           | Continuously follow the stream (default: `true`)                        |
| `--kind <prefix>`    | Filter by subject/kind prefix — supports `*` globs (e.g., `detector.*`) |
| `--severity <level>` | Filter by severity (`debug`\|`info`\|`warn`\|`error`\|`fatal`)          |
| `--since <duration>` | Seed window (e.g., `5m`, `1h`)                                          |
| `--consumer-id <id>` | Persistent consumer id for cursor resume                                |
| `--json`             | Output as NDJSON                                                        |

```bash theme={"dark"}
# Follow all detector events at warn-or-higher severity
genie events stream-follow --kind 'detector.*' --severity warn

# Resume from a previous cursor under a stable consumer id
genie events stream-follow --consumer-id sentinel-ingest --since 5m --json
```

### `genie events subscribe`

Mint a signed subscription token for `genie events stream --follow`. Tokens carry an RBAC role and optional restrictions on event types, LISTEN channels, TTL, and tenant — letting subscriber agents connect without sharing long-lived credentials.

<Note>
  `subscribe` requires a running scheduler/issuer with HMAC keys configured. The `--types` and `--channels` flags narrow (never widen) the role's default permissions.
</Note>

```bash theme={"dark"}
genie events subscribe [options]
```

| Option                 | Description                                                                       |
| ---------------------- | --------------------------------------------------------------------------------- |
| `--role <role>`        | RBAC role: `events:admin`\|`events:operator`\|`events:subscriber`\|`events:audit` |
| `--types <csv>`        | Comma-separated allowed event types (subset of role defaults)                     |
| `--channels <csv>`     | Comma-separated allowed LISTEN channels (subset of role defaults)                 |
| `--ttl <duration>`     | Token time-to-live (e.g., `30m`, `1h`, `24h`). Defaults to `1h`.                  |
| `--tenant <id>`        | Tenant id. Defaults to `default`.                                                 |
| `--subscriber-id <id>` | Stable id for the subscriber agent                                                |
| `--json`               | Output as JSON                                                                    |

```bash theme={"dark"}
genie events subscribe \
  --role events:operator \
  --subscriber-id sentinel-ingest \
  --ttl 24h \
  --json
```

### `genie events errors`

Show aggregated error patterns.

```bash theme={"dark"}
genie events errors [--since <duration>] [--json]
```

<Warning>
  Treat `genie events errors` as an incident-response tool. A sudden spike in an error pattern usually means a provider outage, a credential rotation, or a broken agent — investigate before spawning more work on top.
</Warning>

### `genie events costs`

Cost breakdown from OTel API request events.

```bash theme={"dark"}
genie events costs [options]
```

| Option               | Description                  |
| -------------------- | ---------------------------- |
| `--today`            | Show costs from the last 24h |
| `--since <duration>` | Time window (default: `24h`) |
| `--by-agent`         | Group by agent               |
| `--by-wish`          | Group by wish                |
| `--by-model`         | Group by model               |
| `--json`             | Output as JSON               |

```bash theme={"dark"}
genie events costs --today --by-agent
genie events costs --since 7d --by-model
```

<Tip>
  Every `genie events` subcommand supports `--json`. Pipe into `jq` for ad-hoc analysis — e.g., `genie events costs --since 7d --by-model --json | jq '.[] | select(.usd > 1)'` surfaces only models that cost more than \$1 in the last week.
</Tip>

### `genie events tools`

Tool usage analytics from OTel tool events.

```bash theme={"dark"}
genie events tools [options]
```

| Option               | Description                  |
| -------------------- | ---------------------------- |
| `--since <duration>` | Time window (default: `24h`) |
| `--by-tool`          | Group by tool name (default) |
| `--by-agent`         | Group by agent               |
| `--json`             | Output as JSON               |

### `genie events timeline`

Full event timeline for a task, agent, wish, or trace ID. Shows all events associated with a specific entity in chronological order.

```bash theme={"dark"}
genie events timeline <entity-id> [--json]
```

```bash theme={"dark"}
genie events timeline task-6c3a2cf2
genie events timeline engineer-1
```

### `genie events timeline-v2`

Render a causal tree for a `trace_id` from the enriched `genie_runtime_events` surface. Unlike `timeline`, which walks any entity type, `timeline-v2` expects a trace id and reconstructs spans with OTel-style parent/child relationships — use it when chasing causality across agent/tool boundaries.

```bash theme={"dark"}
genie events timeline-v2 <trace-id> [options]
```

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

```bash theme={"dark"}
genie events timeline-v2 01JABCDEF0123456789GHJKMN --json
```

### `genie events summary`

High-level stats: agents spawned, tasks moved, costs, errors.

```bash theme={"dark"}
genie events summary [--today] [--since <duration>] [--json]
```

### `genie events scan`

Full server cost scan via ccusage. Scans all Claude Code sessions on the machine, not just genie-spawned ones.

```bash theme={"dark"}
genie events scan [options]
```

| Option           | Description                     |
| ---------------- | ------------------------------- |
| `--since <date>` | Start date in `YYYYMMDD` format |
| `--json`         | Output as JSON                  |
| `--breakdown`    | Show per-model breakdown        |

```bash theme={"dark"}
genie events scan
genie events scan --since 20260330 --breakdown
```

### `genie events migrate`

Backfill legacy `audit_events` rows into `genie_runtime_events` as a one-shot migration. Useful when adopting the v2 enriched surface on an existing installation or recovering from a gap in the ingestion pipeline.

<Note>
  Run with `--dry-run` first to inspect row deltas; re-run without `--dry-run` to commit.
</Note>

```bash theme={"dark"}
genie events migrate [options]
```

| Option               | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `--audit`            | Migrate `audit_events` → `genie_runtime_events` with sentinel source tag |
| `--dry-run`          | Report row deltas without writing                                        |
| `--since <duration>` | Only migrate rows created within this window                             |
| `--limit <n>`        | Cap the number of rows migrated per run                                  |
| `--json`             | Output summary as JSON                                                   |

```bash theme={"dark"}
genie events migrate --audit --since 7d --dry-run
genie events migrate --audit --since 7d --limit 10000 --json
```

### `genie events admin`

Incident-response admin commands (sentinel H6 audited). Every subcommand emits its own audit event so operator actions remain traceable in the chain.

```bash theme={"dark"}
genie events admin <subcommand> [options]
```

| Subcommand              | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `export-audit`          | Produce a signed audit-chain bundle (emits `audit.export`)               |
| `list-revocations`      | List revoked token ids for a tenant                                      |
| `revoke-subscriber`     | Add a subscription token to the revocation list                          |
| `rotate-redaction-keys` | Rotate redaction + audit HMAC keys, preserving prior versions for lookup |
| `un-hash`               | Admin reverse-lookup for a Tier-A hash (emits `audit.un_hash`)           |
| `verify-chain`          | Quick chain-integrity check (no export)                                  |

```bash theme={"dark"}
genie events admin verify-chain
genie events admin export-audit --tenant default
```

Run `genie events admin <subcommand> --help` for per-subcommand flags.

### Enriched (v2) surface

"Enriched" refers to the `genie_runtime_events` table — a v2 superset of the legacy `audit_events` stream that adds OTel-style columns (`trace_id`, `span_id`, `severity`, `duration_ms`) plus a hierarchical `kind` taxonomy. It has no dedicated subcommand; instead, the enriched surface is reached via:

* [`genie events list --v2`](#genie-events-list) — table listing with enriched columns and `--kind`/`--severity` filters
* [`genie events stream-follow`](#genie-events-stream-follow) — resumable `LISTEN/NOTIFY` stream with glob-enabled `--kind`
* [`genie events timeline-v2`](#genie-events-timeline-v2) — causal-tree rendering for a `trace_id`
* [`genie events migrate --audit`](#genie-events-migrate) — backfill legacy rows into the enriched surface

Use the v2 surface whenever you need trace/span correlation or subject-tree subscriptions; fall back to the legacy commands for simple audit queries.

***

## Log

The `genie log` command provides a unified observability feed that aggregates transcripts, DMs, team chat, tool calls, and system events into a single stream.

### `genie log`

Unified observability feed for an agent or team.

```bash theme={"dark"}
genie log [agent] [options]
```

| Option                | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| `--team <name>`       | Show interleaved feed for all agents in a team                                |
| `--type <kind>`       | Filter by event kind: `transcript`, `message`, `tool_call`, `state`, `system` |
| `--since <timestamp>` | Only events after ISO timestamp                                               |
| `--last <n>`          | Show last N events                                                            |
| `--ndjson`            | Output as newline-delimited JSON (pipeable to jq)                             |
| `--json`              | Output as pretty JSON                                                         |
| `-f, --follow`        | Follow mode — real-time streaming                                             |

```bash theme={"dark"}
# Follow an agent's live feed
genie log engineer -f

# Show last 20 events for the whole team
genie log --team auth-rewrite --last 20

# Stream tool calls as NDJSON
genie log engineer --type tool_call --ndjson -f
```

***

## Brief

`genie brief` shows an aggregated startup brief with context since the last session — useful for agents resuming work or operators reviewing what happened overnight.

### `genie brief`

```bash theme={"dark"}
genie brief [options]
```

| Option           | Description                                      |
| ---------------- | ------------------------------------------------ |
| `--team <name>`  | Team name (default: `GENIE_TEAM` env var)        |
| `--agent <name>` | Agent name (default: `GENIE_AGENT_NAME` env var) |
| `--since <iso>`  | Start timestamp (default: last executor end)     |

```bash theme={"dark"}
# Show brief for the current agent
genie brief

# Show brief for a specific team since midnight
genie brief --team auth-rewrite --since 2026-03-30T00:00:00Z
```

***

## Sessions

The `genie sessions` command group provides history and search across Claude Code sessions. Session metadata and content are stored in PostgreSQL.

### `genie sessions list`

List Claude Code sessions.

```bash theme={"dark"}
genie sessions list [options]
```

| Option           | Description                 |
| ---------------- | --------------------------- |
| `--active`       | Show only active sessions   |
| `--orphaned`     | Show only orphaned sessions |
| `--agent <name>` | Filter by agent             |
| `--limit <n>`    | Max rows returned           |
| `--json`         | Output as JSON              |

### `genie sessions replay`

Replay a session — interleaves content and events in chronological order.

```bash theme={"dark"}
genie sessions replay <session-id> [--json]
```

### `genie sessions search`

Full-text search across session content.

```bash theme={"dark"}
genie sessions search <query> [--limit <n>] [--json]
```

### `genie sessions sync`

Sync session data from JSONL files into PostgreSQL.

```bash theme={"dark"}
genie sessions sync
```

***

## Metrics

The `genie metrics` command group provides machine-level state snapshots and agent heartbeat data.

### `genie metrics now`

Current machine state — CPU, memory, active agents, teams.

```bash theme={"dark"}
genie metrics now [--json]
```

### `genie metrics history`

Machine snapshot history over time.

```bash theme={"dark"}
genie metrics history [--since <duration>] [--json]
```

Default time window is `1h`. Supports durations like `6h`, `1d`.

### `genie metrics agents`

Per-agent heartbeat summary — shows each agent's last heartbeat, state, and uptime.

```bash theme={"dark"}
genie metrics agents [--json]
```

***

## Schedule

The `genie schedule` command group manages cron-based scheduled triggers.

### `genie schedule create`

Create a new schedule.

```bash theme={"dark"}
genie schedule create <name> [options]
```

### `genie schedule list`

List schedules with next due trigger.

```bash theme={"dark"}
genie schedule list [options]
```

### `genie schedule cancel`

Cancel a schedule and skip pending triggers.

```bash theme={"dark"}
genie schedule cancel <name> [options]
```

### `genie schedule retry`

Reset a failed trigger to pending.

```bash theme={"dark"}
genie schedule retry <name>
```

### `genie schedule history`

Show past executions for a schedule.

```bash theme={"dark"}
genie schedule history <name> [options]
```

***

## QA

The `genie qa` command group runs self-testing specs against the Genie CLI itself.

### `genie qa run`

Run QA specs — all, a domain, or a single spec.

```bash theme={"dark"}
genie qa run [target] [options]
```

| Option                | Description                                 |
| --------------------- | ------------------------------------------- |
| `--timeout <seconds>` | Max seconds per spec (default: `3600`)      |
| `--parallel <n>`      | Max specs to run in parallel (default: `5`) |
| `--verbose`           | Show all collected events                   |
| `--ndjson`            | Machine-readable NDJSON output              |

### `genie qa status`

Show QA dashboard with last results per spec.

```bash theme={"dark"}
genie qa status [options]
```

### `genie qa history`

Show recent QA runs.

```bash theme={"dark"}
genie qa history
```

### `genie qa check`

Evaluate a QA spec against current team logs and publish a qa-report.

```bash theme={"dark"}
genie qa check <specFile> [options]
```

| Option                | Description                                   |
| --------------------- | --------------------------------------------- |
| `--team <name>`       | Team name (defaults to `GENIE_TEAM`)          |
| `--since <timestamp>` | Only consider events after this ISO timestamp |
| `--since-file <path>` | Read the lower-bound timestamp from a file    |

```bash theme={"dark"}
genie qa check specs/messaging.yaml
genie qa check specs/messaging.yaml --team auth-rewrite --since 2026-03-30T00:00:00Z
```

### `genie qa-report`

Publish a QA result to the PostgreSQL event log. Called internally by the QA team-lead.

```bash theme={"dark"}
genie qa-report <json>
```

## See also

<CardGroup cols={2}>
  <Card title="Spawn & Lifecycle" icon="rocket" href="/genie/cli/spawn">
    Spawn the agents whose events land in the audit log.
  </Card>

  <Card title="Messaging" icon="message" href="/genie/cli/messaging">
    Send instructions to agents instead of scraping terminal output.
  </Card>

  <Card title="Scheduling" icon="clock" href="/genie/cli/scheduling">
    Configure cron triggers whose runs surface through `schedule history`.
  </Card>

  <Card title="Database" icon="database" href="/genie/cli/database">
    Inspect the PostgreSQL store that backs every event, session, and metric.
  </Card>
</CardGroup>