Event System

Ignition has an event pipeline for observability. When an EventBus is attached, significant actions during a run emit structured events that the dashboard and NDJSON log sinks can consume.

In the current CLI, an EventBus is created when dashboard streaming is active or when --log-dir is set. Plain terminal reporters still render directly and do not currently consume the event stream.

Event types

Eight event types cover the full lifecycle:

Run events

Event	Description
`run_started`	Run begins. Payload: `mode`, `errorMode`, `hostCount`
`run_finished`	Run ends. Payload: `durationMs`, `hasFailures`, `hostCount`

Host events

Event	Description
`host_started`	Host execution begins. Payload: `host`
`host_finished`	Host execution ends. Payload: `host`, `ok`, `changed`, `failed`, `durationMs`, `cancelled`

Resource events

Event	Description
`resource_started`	Resource execution begins. Payload: `resourceType`, `resourceName`
`resource_finished`	Resource execution ends. Payload: `resourceType`, `resourceName`, `status`, `durationMs`, `error`, `cacheHit`
`resource_retry`	A retryable error triggered a retry. Payload: `resourceType`, `resourceName`, `phase`, `error`, `durationMs`
`resource_output`	Streaming output chunk. Payload: `resourceType`, `resourceName`, `stream` (`"stdout"` or `"stderr"`), `chunk`

Event structure

Every event extends BaseEvent:

interface BaseEvent {
  type: EventType
  timestamp: string // ISO 8601
  correlation: {
    runId: string
    hostId?: string
    resourceId?: string
    attempt?: number
  }
}

Each run generates a unique runId (12 hex chars) for correlation. All events within a run share this ID.

NDJSON log files

Use --log-dir to write events as newline-delimited JSON:

ignition run deploy.ts @web --log-dir ./logs

This creates files like logs/2026-03-02T14-22-08Z_a1b2c3d4e5f6.ndjson. Each line is a complete JSON object. This format is compatible with tools like jq:

# Show all event types
jq -r ".type" ./logs/*.ndjson

# Show only failures
jq 'select(.type == "resource_finished" and .status == "failed")' ./logs/*.ndjson

Event flow diagram

Recipe execution
  ├── run_started
  ├── host_started (per host)
  │     ├── resource_started
  │     ├── resource_output (streaming, 0..n)
  │     ├── resource_retry (on transient failure, 0..n)
  │     ├── resource_finished
  │     └── ... more resources
  ├── host_finished (per host)
  └── run_finished