monitor.session

Session framing for live monitor runs (spec 2026-07-12).

The collector stays session-blind: one process run == one live session, and the frame is stamped at the edges (CLI at launch, shutdown hook at exit).

class otto.monitor.session.SessionFrame(id: str, label: str | None, note: str | None, start: datetime, end: datetime | None = None)

Bases: object

Identity + lifetime of one live monitoring session.

end is None means still-open — a crash never rewrites history, and readers fall back to the last sample’s timestamp (producer’s job).

id : str
label : str | None
note : str | None
start : datetime
end : datetime | None = None
otto.monitor.session.new_frame(label: str | None, note: str | None, *, now: datetime | None = None) → SessionFrame

Create a frame stamped at now (wall-clock UTC when omitted).

The id is the UTC start time as a filesystem/URL-safe slug — unique per database because two live runs can’t write one file (flock guard).

otto.monitor.session.snapshot_lab(hosts: Sequence[RemoteHost], declared: list[Link]) → LabSnapshot

Freeze the view-relevant lab config into a session snapshot.

Static links only (implicit hop edges + declared routes; contract spec 2026-07-10 §2) — dynamic/tunnel links are runtime state and never enter a snapshot. Credentials never leave the host object. elements stays empty: real labs declare membership per-host (element field) and the frontend derives the grouping, exactly as with generator fixtures.

A link is exported only when both endpoints resolve to a host in this snapshot, mirroring the fixture generator’s _implicit_links. That drops the local edge implicit_links gives every hop-less host: the local root is the frontend’s own synthesized node (Plan 4 topology), never a RemoteHost, so a local endpoint in the document would be a phantom. The same filter drops a declared link naming an unknown host.

Parameters:

  • hosts – Hosts to include, in the caller’s order.

  • declared – Already-resolved declared links (see otto.link.derive.resolve_declared_links) — resolution against the active lab config is the CLI’s job, not this pure module’s.

Returns:

The frozen LabSnapshot.

otto.monitor.session.snapshot_lab_json(hosts: Sequence[RemoteHost], declared: list[Link]) → str

Build the same snapshot as snapshot_lab(), serialized to JSON.

Parameters:

  • hosts – Hosts to include, in the caller’s order.

  • declared – Already-resolved declared links.

Returns:

The JSON-encoded snapshot, ready to hand to the DB (lab_json) or the server.