stormlog.infer.correlation_events

Versioned, engine-neutral inference execution records.

The v1 endpoint records in stormlog.infer.events remain client observations. These v2 records describe server execution without assigning shared work to individual requests merely because they participated in it.

Functions

`activity_busy_intervals`(activity)	The intervals in which a GPU activity kept its device busy, or None.
`load_inference_artifact`(path)	Read mixed legacy and correlation records in their original order.
`parse_inference_record`(record)	Parse one v1 or v2 JSONL record without fabricating missing evidence.

Classes

`ActivityReferenceEvent`(*, context, event_id)	A scoped trace activity and its optional link to an iteration.
`ArtifactIdentityEvent`(*, context, event_id)	Versioned run identity for an inference JSONL artifact.
`CapabilityEvent`(*, context, event_id[, ...])	Availability and outcome for one optional capture component.
`ClockAlignmentEvent`(*, context, event_id[, ...])	Offset and uncertainty for comparing two distinct clock domains.
`CorrelationContext`(run_id, session_id, ...)	Capture identity and evidence quality shared by one emitted record.
`CorrelationEvent`(*, context, event_id[, ...])	Common event identity; subclasses own their event-specific evidence.
`EntityRef`(producer_id, id)	An ID scoped to its producer within a run.
`IterationEvent`(*, context, event_id[, ...])	One server execution iteration, recorded once for all participants.
`LegacyInferenceRecord`(raw)	An unchanged v1 record; server correlation remains unknown.
`MembershipEvent`(*, context, event_id[, ...])	One request's role in one shared execution iteration.
`RequestEvent`(*, context, event_id[, ...])	One logical request observation; attempts are separate identities.
`StageEvent`(*, context, event_id[, metadata, ...])	A generic named stage span, for LLM and non-LLM workloads.

class stormlog.infer.correlation_events.ActivityReferenceEvent(*, context, event_id, metadata=<factory>, activity_ref, activity_kind, attribution_status, activity_domain='unknown', iteration_ref=None, correlation_scope=None, trace_attachment_id=None, runtime_correlation_id=None, cuda_correlation_id=None, stream_id=None, graph_id=None, start_ns=None, end_ns=None)[source]

Bases: CorrelationEvent

A scoped trace activity and its optional link to an iteration.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
activity_ref (EntityRef)
activity_kind (str)
attribution_status (str)
activity_domain (str)
iteration_ref (EntityRef | None)
correlation_scope (EntityRef | None)
trace_attachment_id (str | None)
runtime_correlation_id (int | None)
cuda_correlation_id (int | None)
stream_id (int | None)
graph_id (int | None)
start_ns (int | None)
end_ns (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.activity_ref'

activity_ref: EntityRef

activity_kind: str

attribution_status: str

activity_domain: str = 'unknown'

iteration_ref: EntityRef | None = None

correlation_scope: EntityRef | None = None

trace_attachment_id: str | None = None

runtime_correlation_id: int | None = None

cuda_correlation_id: int | None = None

stream_id: int | None = None

graph_id: int | None = None

start_ns: int | None = None

end_ns: int | None = None

property schema_version: int: Busy intervals change what the span means, so they take version 3.

class stormlog.infer.correlation_events.ArtifactIdentityEvent(*, context, event_id, metadata=<factory>, artifact_kind, created_at_ns)[source]

Bases: CorrelationEvent

Versioned run identity for an inference JSONL artifact.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
artifact_kind (str)
created_at_ns (int)

EVENT_TYPE: ClassVar[str] = 'infer.artifact'

artifact_kind: str

created_at_ns: int

class stormlog.infer.correlation_events.CapabilityEvent(*, context, event_id, metadata=<factory>, component, available, supported=<factory>, enabled=<factory>, collected=<factory>)[source]

Bases: CorrelationEvent

Availability and outcome for one optional capture component.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
component (str)
available (bool)
supported (list[str])
enabled (list[str])
collected (list[str])

EVENT_TYPE: ClassVar[str] = 'infer.capabilities'

component: str

available: bool

supported: list[str]

enabled: list[str]

collected: list[str]

class stormlog.infer.correlation_events.ClockAlignmentEvent(*, context, event_id, metadata=<factory>, from_clock_domain, to_clock_domain, offset_ns, uncertainty_ns, valid_from_ns=None, valid_to_ns=None)[source]

Bases: CorrelationEvent

Offset and uncertainty for comparing two distinct clock domains.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
from_clock_domain (str)
to_clock_domain (str)
offset_ns (int)
uncertainty_ns (int)
valid_from_ns (int | None)
valid_to_ns (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.clock_alignment'

from_clock_domain: str

to_clock_domain: str

offset_ns: int

uncertainty_ns: int

valid_from_ns: int | None = None

valid_to_ns: int | None = None

class stormlog.infer.correlation_events.CorrelationContext(run_id, session_id, producer_id, source, clock_domain, clock_kind, collection_mode, provenance, source_version=None, engine=None, engine_version=None, backend=None, backend_version=None, host=None, pid=None, device_uuid=None, rank=None, local_rank=None, world_size=None)[source]

Bases: object

Capture identity and evidence quality shared by one emitted record.

Parameters:

run_id (str)
session_id (str)
producer_id (str)
source (str)
clock_domain (str)
clock_kind (str)
collection_mode (str)
provenance (str)
source_version (str | None)
engine (str | None)
engine_version (str | None)
backend (str | None)
backend_version (str | None)
host (str | None)
pid (int | None)
device_uuid (str | None)
rank (int | None)
local_rank (int | None)
world_size (int | None)

run_id: str

session_id: str

producer_id: str

source: str

clock_domain: str

clock_kind: str

collection_mode: str

provenance: str

source_version: str | None = None

engine: str | None = None

engine_version: str | None = None

backend: str | None = None

backend_version: str | None = None

host: str | None = None

pid: int | None = None

device_uuid: str | None = None

rank: int | None = None

local_rank: int | None = None

world_size: int | None = None

class stormlog.infer.correlation_events.CorrelationEvent(*, context, event_id, metadata=<factory>)[source]

Bases: object

Common event identity; subclasses own their event-specific evidence.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])

context: CorrelationContext

event_id: str

metadata: dict[str, Any]

EVENT_TYPE: ClassVar[str]

property schema_version: int

to_record()[source]

Return type:: dict[str, Any]

property elapsed_ns: int | None: Only local monotonic spans have an unqualified duration.

class stormlog.infer.correlation_events.EntityRef(producer_id, id)[source]

Bases: object

An ID scoped to its producer within a run.

Parameters:

producer_id (str)
id (str)

producer_id: str

id: str

class stormlog.infer.correlation_events.IterationEvent(*, context, event_id, metadata=<factory>, iteration_ref, batch_ref=None, start_ns=None, end_ns=None)[source]

Bases: CorrelationEvent

One server execution iteration, recorded once for all participants.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
iteration_ref (EntityRef)
batch_ref (EntityRef | None)
start_ns (int | None)
end_ns (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.iteration'

iteration_ref: EntityRef

batch_ref: EntityRef | None = None

start_ns: int | None = None

end_ns: int | None = None

class stormlog.infer.correlation_events.LegacyInferenceRecord(raw)[source]

Bases: object

An unchanged v1 record; server correlation remains unknown.

Parameters:: raw (dict[str, Any])

raw: dict[str, Any]

to_record()[source]

Return type:: dict[str, Any]

class stormlog.infer.correlation_events.MembershipEvent(*, context, event_id, metadata=<factory>, request_ref, iteration_ref, role, attempt_ref=None, input_tokens=None, output_tokens=None, kv_bytes=None)[source]

Bases: CorrelationEvent

One request’s role in one shared execution iteration.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
request_ref (EntityRef)
iteration_ref (EntityRef)
role (str)
attempt_ref (EntityRef | None)
input_tokens (int | None)
output_tokens (int | None)
kv_bytes (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.membership'

request_ref: EntityRef

iteration_ref: EntityRef

role: str

attempt_ref: EntityRef | None = None

input_tokens: int | None = None

output_tokens: int | None = None

kv_bytes: int | None = None

class stormlog.infer.correlation_events.RequestEvent(*, context, event_id, metadata=<factory>, request_ref, attempt_ref=None, backend_request_ref=None, start_ns=None, end_ns=None, status=None, input_tokens=None, output_tokens=None, kv_bytes=None)[source]

Bases: CorrelationEvent

One logical request observation; attempts are separate identities.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
request_ref (EntityRef)
attempt_ref (EntityRef | None)
backend_request_ref (EntityRef | None)
start_ns (int | None)
end_ns (int | None)
status (str | None)
input_tokens (int | None)
output_tokens (int | None)
kv_bytes (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.request'

request_ref: EntityRef

attempt_ref: EntityRef | None = None

backend_request_ref: EntityRef | None = None

start_ns: int | None = None

end_ns: int | None = None

status: str | None = None

input_tokens: int | None = None

output_tokens: int | None = None

kv_bytes: int | None = None

class stormlog.infer.correlation_events.StageEvent(*, context, event_id, metadata=<factory>, stage_ref, name, request_ref=None, iteration_ref=None, start_ns=None, end_ns=None, input_tokens=None, output_tokens=None, kv_bytes=None)[source]

Bases: CorrelationEvent

A generic named stage span, for LLM and non-LLM workloads.

Parameters:

context (CorrelationContext)
event_id (str)
metadata (dict[str, Any])
stage_ref (EntityRef)
name (str)
request_ref (EntityRef | None)
iteration_ref (EntityRef | None)
start_ns (int | None)
end_ns (int | None)
input_tokens (int | None)
output_tokens (int | None)
kv_bytes (int | None)

EVENT_TYPE: ClassVar[str] = 'infer.stage'

stage_ref: EntityRef

name: str

request_ref: EntityRef | None = None

iteration_ref: EntityRef | None = None

start_ns: int | None = None

end_ns: int | None = None

input_tokens: int | None = None

output_tokens: int | None = None

kv_bytes: int | None = None

stormlog.infer.correlation_events.activity_busy_intervals(activity)[source]

The intervals in which a GPU activity kept its device busy, or None.

Without metadata.intervals the activity is busy for [start_ns, end_ns), and None means it has no complete span. With them (schema version 3) it is busy only inside those [offset_ns, duration_ns] pairs from start_ns, which must be sorted, disjoint, and inside the span; anything else is a ValueError.

Parameters:: activity (ActivityReferenceEvent)
Return type:: list[tuple[int, int]] | None

stormlog.infer.correlation_events.load_inference_artifact(path)[source]

Read mixed legacy and correlation records in their original order.

Parameters:: path (str | Path)
Return type:: list[CorrelationEvent | LegacyInferenceRecord]

stormlog.infer.correlation_events.parse_inference_record(record)[source]

Parse one v1 or v2 JSONL record without fabricating missing evidence.

Parameters:: record (Mapping[str, Any])
Return type:: CorrelationEvent | LegacyInferenceRecord