Logs & Traces

Akshi captures structured logs from all agents and supports trace-level debugging with replay.

Viewing logs

CLI

# Recent logs
akshi logs

# Follow mode
akshi logs --follow

# Filter by agent
akshi logs --agent log-monitor

# Filter by level
akshi logs --level warn

API

Poll for new log entries:

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:3210/api/v1/logs?since=0&limit=50"

Use next_seq from the response as the since parameter for subsequent calls.

Trace exploration

Traces capture the full execution sequence of an agent tick: inference calls, tool invocations, journal writes, and timing.

# List recent traces
akshi logs --traces

# View a specific trace
akshi logs --trace-id abc123

Traces are stored in the data directory under traces/.

Replay

Replay a recorded agent tick to debug behavior:

akshi replay --trace-id abc123

Replay re-executes the agent with the same inputs and shows a side-by-side comparison of the original and replayed outputs. This is useful for diagnosing non-deterministic behavior.

Log retention

Logs are retained based on the data directory size. Configure rotation:

[identity]
log_retention_days = 30
log_max_size_mb = 500

Structured format

All logs follow the format:

{
  "seq": 155,
  "ts": "2026-03-17T10:00:01Z",
  "level": "info",
  "agent": "log-monitor",
  "message": "Scan cycle completed"
}

Export logs as JSON for external analysis:

akshi logs --format json > logs.json