Event Log

Format

The event log is NDJSON, one JSON object per line, emitted in chronological order. Every object has an "event" field identifying its type and a "ts" field with a Unix timestamp in milliseconds.

Output destination

Events go to stdout. Nanny’s own output, the startup block and any warning, goes to stderr, so redirecting stdout gives you the event log by itself:

nanny run > events.ndjson

Your agent’s own stdout still passes through, since it inherits the stream, so a consumer that wants only events filters for lines beginning with {. In a container, redirect nothing. The runtime collects stdout already and every log shipper reads it from there. A Datadog agent, for example, needs no Nanny configuration at all:

labels:
  com.datadoghq.ad.logs: '[{"source":"nanny","service":"your-app"}]'

If you do want a file inside a container, redirect in the entrypoint rather than piping, so Nanny stays PID 1 and still receives SIGTERM:

exec nanny run > /var/log/nanny/events.ndjson    # redirection survives exec
exec nanny run | tee /var/log/nanny/events.ndjson # a pipe does not: avoid

Durable delivery is Cloud’s job, not the log’s. Nothing on disk survives a container that is replaced. When NANNY_API_KEY is set, undelivered batches are held in .nanny/spool/ and sent on the next run, which is the path worth mounting a volume for. See Connect to Nanny Cloud.

Guaranteed events

Every execution emits exactly these two events, in this order:

ExecutionStarted

Always the first event. Emitted immediately before the child process is spawned.

{
  "event": "ExecutionStarted",
  "ts": 1711234567000,
  "run_id": "a1b2c3d4",
  "seq": 0,
  "command": "python agent.py",
  "allowed_tools": ["web_search", "send_outreach"],
  "tool_labels": {
    "web_search": ["reads_untrusted"],
    "send_outreach": ["external_effect"]
  },
  "config_hash": "9f2a41c8"
}

ExecutionStopped

Always the last event of a complete run. Emitted on every exit path: clean exit, a policy stop, an error, or a signal.

{
  "event": "ExecutionStopped",
  "ts": 1711234572000,
  "run_id": "a1b2c3d4",
  "seq": 12,
  "reason": "AgentCompleted",
  "tokens_spent": 70,
  "elapsed_ms": 4823
}

If this event is missing from a run, the process crashed. That absence is itself a fact worth reading. reason is one of four: ToolDenied, RuleDenied, AgentCompleted, or ManualStop. Only the first two are policy violations.

SDK events

When the Rust SDK macros or Python SDK decorators are active, additional events are emitted for each tool call. These appear between ExecutionStarted and ExecutionStopped:

Event	When emitted
`ToolAllowed`	When Nanny permits a tool call
`ToolDenied`	When a tool call is blocked because the tool is not in the allowlist
`RuleDenied`	When a tool call is blocked by a custom rule or a per-tool `max_calls` limit
`ToolFailed`	When a permitted tool fails at runtime (network error, bad args, etc.)
`AgentScopeEntered`	When a `#[nanny::agent("name")]` function is entered
`AgentScopeExited`	When a `#[nanny::agent("name")]` function returns
`RulesDeclared`	Once, when the agent declares which rules it registered

ToolDenied and RuleDenied are distinct denial events. ToolDenied means the tool was not permitted at all; RuleDenied means the tool was permitted but a rule blocked this specific call. ToolFailed is different from both: the tool was allowed and called, but hit a runtime error. No tokens are recorded for a failure.

Using the log

The event log is designed to be piped into standard tools:

# Every event for one run, in order
cat nanny.log | jq -c 'select(.run_id == "a1b2c3d4")' | sort -t: -k3 -n

# Find all denied tool calls (allowlist blocks and rule denials)
cat nanny.log | jq 'select(.event == "ToolDenied" or .event == "RuleDenied")'

# Check why a run stopped
cat nanny.log | jq 'select(.event == "ExecutionStopped") | .reason'

Concepts

SDKs

Guides

CLI

Reference

Format

Output destination

Guaranteed events

ExecutionStarted

ExecutionStopped

SDK events

Using the log

​Format

​Output destination

​Guaranteed events

​ExecutionStarted

​ExecutionStopped

​SDK events

​Using the log

Format

Output destination

Guaranteed events

ExecutionStarted

ExecutionStopped

SDK events

Using the log