Events

7 min read

Provium's host-side scheduler and runners emit observability events that drive the human-readable summary, the --json output, provium-coverage, and any other consumer that wants to follow what the harness is doing.

The transport is length-prefixed msgpack frames (the same framing as the wire protocol). Get them via --save-events <path>, --events-stdout, or --events-socket <path>.

Frame shape #

Each frame is an EventFrame:

{
  "ts":      <i64>,    // ns since Unix epoch, host clock at emission
  "kind":    "<name>", // discriminator (snake_case)
  "payload": { … }     // variant-specific
}

The Event enum is flattened into the envelope so kind and payload appear at the top level of each frame.

PROTOCOL_VERSION (currently 1) is bumped on any wire-shape change. Adding a new variant or field is a strict version bump; removing or renaming one is breaking. See protocol version for the pinning policy.

File lifecycle #

file_discovered #

Emitted once per *.test.lua file before any dispatching begins.

file_dispatched #

A test file was picked up by a runner thread.

file_blocked #

A test file is waiting on the resource pool or PSI pressure.

file_completed #

A test file finished — successfully, with failures, or terminated by timeout / panic.

crashed means the runner panicked or hit a test-infrastructure failure; remaining tests in the file are marked failed-due-to-poisoned-state.

Test lifecycle #

test_started #

A test() block within a file started.

test_skipped #

The test was filtered or marked Skipped (declarative meta.skip, inline t:skip(), file-scope todo(), or tag/slow filter).

test_passed #

test_failed #

VM lifecycle #

vm_spawned #

vm_shutdown #

Pool and claims #

pool_state #

Periodic snapshot of resource-pool usage. Default cadence: 1 Hz.

claim_acquired #

A file successfully claimed resources via provium:claim(...).

claim_released #

A file released its claim. Pairs with claim_acquired on the same path.

Fixtures #

fixture_build_started #

fixture_build_done #

fixture_build_waiting #

A second file is waiting on the build lock another file holds.

fixture_cache_hit #

A fixture was resumed from its cached snapshot — no rebuild required.

Shared types #

ResourceAmount #

{
  "memory_bytes": <u64>,
  "cpus":         <u32>
}

Used in pool / claim / reservation events.

MetaMap and MetaValue #

MetaMap is BTreeMap<String, MetaValue>. MetaValue is a tagged-by-type union over native msgpack types:

The deserialiser dispatches on the input type rather than relying on declaration-order fallthrough, so valid-UTF-8 byte sequences are not mis-classified as strings.

Event guarantees #

• file_discovered for every discovered file, before any dispatching.
• For each file: at most one file_dispatched, optional file_blocked(s) before it, exactly one file_completed after.
• For each test: exactly one test_started, then exactly one of test_passed / test_failed / test_skipped.
• claim_acquired and claim_released are paired per file.
• fixture_build_started and fixture_build_done are paired per build. A fixture_build_waiting may precede the _done if the file queued behind a peer.
• fixture_cache_hit fires AFTER successful restore — never on a corrupt entry that turns into a rebuild.

Consuming the stream #

The three output channels — --save-events <path> (file), --events-stdout (pipe), and --events-socket <path> (multi-consumer Unix socket) — and the patterns for choosing between them are covered in events and coverage.

See also #

• CLI — flags that produce / consume events.
• Protocol version — wire-shape pinning policy.
• Events and coverage — patterns for using the event stream.

Edit this page