Bloccs.Trace (bloccs v0.2.0)

Copy Markdown View Source

Records an execution trace of a running network by attaching to bloccs telemetry, and derives structural-coverage obligations from it.

A recording observes two events, scoped to one network:

  • [:bloccs, :node, :start] — a message reached a node's in-port ({:port_in, node, in_port}).
  • [:bloccs, :emit] — a node emitted on an out-port ({:port_out, node, out_port}) and traversed each downstream edge ({:edge, {from_node, from_port}, {to_node, to_port}}).

Those obligation shapes match Bloccs.Coverage, so a trace's reached/1 set feeds Bloccs.Coverage.report/2 directly.

Recording

rec = Bloccs.Trace.record(:events)
# ... feed messages through the network ...
events = Bloccs.Trace.stop(rec)
reached = Bloccs.Trace.reached(events)

Persistence

dump/3 writes a .bloccs-trace file (JSON: {network, events}); load/1 reads one back into the same event list. The format is deliberately legible — a trace is part of the IR you can inspect.

Summary

Types

endpoint()
event()
recording()

Functions

dump(events, network_id, path)

Write events to a .bloccs-trace file (JSON) for network network_id.

load(path)

Load a .bloccs-trace file back into an event list.

reached(events)

Derive the set of reached Bloccs.Coverage obligations from events.

record(network_id)

Start recording the trace for network_id. Returns a recording handle.

stop(map)

Stop recording; detach the handler and return the events in order.

Types

endpoint()

@type endpoint() :: {atom(), atom()}

event()

@type event() :: {:port_in, atom(), atom()} | {:emit, atom(), atom(), [endpoint()]}

recording()

@type recording() :: %{
  network: atom(),
  handler: {module(), atom(), reference()},
  agent: pid()
}

Functions

dump(events, network_id, path)

@spec dump([event()], atom(), Path.t()) :: :ok | {:error, term()}

Write events to a .bloccs-trace file (JSON) for network network_id.

load(path)

@spec load(Path.t()) :: {:ok, [event()]} | {:error, term()}

Load a .bloccs-trace file back into an event list.

reached(events)

@spec reached([event()]) :: [Bloccs.Coverage.obligation()]

Derive the set of reached Bloccs.Coverage obligations from events.

record(network_id)

Start recording the trace for network_id. Returns a recording handle.

stop(map)

@spec stop(recording()) :: [event()]

Stop recording; detach the handler and return the events in order.