stormlog.infer.vllm_execution_log

Read the vLLM execution hook’s raw log (docs/vllm_execution.md).

The hook writes one directory per process lifetime, an epoch, under <host>-<boot>/<role>-<pid>-<start ns>/: sealed segments NNNNNN.jsonl, one open NNNNNN.jsonl.part, a status.json the writer overwrites every second, and a key for pseudonyms. Every record carries the epoch and a sequence number, so a reader takes sealed segments whole and only the complete lines of an open one, and tells records apart by (epoch, seq) rather than by the file they came from. Nothing here interprets the records; the reducer in vllm_execution does.

Functions

read_execution_log(directory, *[, ...])

Read every epoch under directory.

Classes

EpochRead(directory, host_boot, epoch, role, ...)	What one epoch directory held when it was read.
Importer(host, boot_id, monotonic_ns)	Where a read runs: its host, boot and monotonic clock, for judging an epoch's liveness on the clock that wrote it.
LogRead(directory, epochs[, notes])	Every epoch under a hook directory, read once.
RawRecord(epoch, seq, kind, data)	One line of the raw log, as written.

class stormlog.infer.vllm_execution_log.EpochRead(directory, host_boot, epoch, role, pid, start_ns, records=<factory>, hello=None, goodbye=None, status=None, key=None, last_seq=None, contiguous_seq=None, writer_last_seq=None, high_water_before=None, truncated=False, gaps=0, errors=<factory>, last_seen_wall_ns=None, last_seen_mono_ns=None, state='alive', state_reason=None)

Bases: object

What one epoch directory held when it was read.

Parameters:

• directory (Path)

• host_boot (str)

• epoch (str)

• role (str)

• pid (int)

• start_ns (int)

• records (list[RawRecord])

• hello (dict[str, Any] | None)

• goodbye (dict[str, Any] | None)

• status (dict[str, Any] | None)

• key (bytes | None)

• last_seq (int | None)

• contiguous_seq (int | None)

• writer_last_seq (int | None)

• high_water_before (int | None)

• truncated (bool)

• gaps (int)

• errors (list[str])

• last_seen_wall_ns (int | None)

• last_seen_mono_ns (int | None)

• state (str)

• state_reason (str | None)

directory: Path

host_boot: str

epoch: str

role: str

pid: int

start_ns: int

records: list[RawRecord]

hello: dict[str, Any] | None = None

goodbye: dict[str, Any] | None = None

status: dict[str, Any] | None = None

key: bytes | None = None

last_seq: int | None = None

contiguous_seq: int | None = None

writer_last_seq: int | None = None

high_water_before: int | None = None

truncated: bool = False

gaps: int = 0

errors: list[str]

last_seen_wall_ns: int | None = None

last_seen_mono_ns: int | None = None

state: str = 'alive'

state_reason: str | None = None

property host: str

The hello’s host; the directory name cannot be split reliably, since both a hostname and a boot ID may contain dashes.

property boot_id: str | None

of_kind(kind)

Parameters:

kind (str)

Return type:

list[RawRecord]

property consumed_seq: int | None

the contiguous sequence, never the writer’s count from status.json.

Type:

The mark an import may advance to from this read alone

summary()

The epoch’s state for an import summary; no record content.

Return type:

dict[str, Any]

class stormlog.infer.vllm_execution_log.Importer(host, boot_id, monotonic_ns)

Bases: object

Where a read runs: its host, boot and monotonic clock, for judging an epoch’s liveness on the clock that wrote it.

Parameters:

• host (str)

• boot_id (str | None)

• monotonic_ns (int)

host: str

boot_id: str | None

monotonic_ns: int

classmethod here()

Return type:

Importer

shares_clock_with(epoch)

Same host and boot means the same CLOCK_MONOTONIC.

Parameters:

epoch (EpochRead)

Return type:

bool

class stormlog.infer.vllm_execution_log.LogRead(directory, epochs, notes=<factory>)

Bases: object

Every epoch under a hook directory, read once.

Parameters:

• directory (Path)

• epochs (list[EpochRead])

• notes (list[str])

directory: Path

epochs: list[EpochRead]

notes: list[str]

engines()

Return type:

list[EpochRead]

workers()

Return type:

list[EpochRead]

class stormlog.infer.vllm_execution_log.RawRecord(epoch, seq, kind, data)

Bases: object

One line of the raw log, as written.

Parameters:

• epoch (str)

• seq (int)

• kind (str)

• data (dict[str, Any])

epoch: str

seq: int

kind: str

data: dict[str, Any]

stormlog.infer.vllm_execution_log.read_execution_log(directory, *, high_water=None, importer=None, server_stopped=False)

Read every epoch under directory.

high_water maps an epoch name to the highest seq a previous import took; records at or below it are not returned again, though they still count towards the epoch’s gaps and last sequence. importer is where this read runs (here, by default): an epoch’s silence is judged only when the importer shares the epoch’s host and boot, on the monotonic clock. server_stopped says the server that wrote the log is no longer running, so an epoch without goodbye is gone.

Parameters:

• directory (str | Path)

• high_water (dict[str, int] | None)

• importer (Importer | None)

• server_stopped (bool)

Return type:

LogRead