stormlog.derived_fields

Registry-driven derived-field layer for Stormlog telemetry.

Centralises the common investigation formulas (allocator gap, utilisation %, fragmentation ratio, degraded-collector state) so that diagnose.py, gap_analysis.py, and future TUI surfaces all use a single, tested source of truth instead of copy-pasting the same arithmetic.

Usage:

from stormlog.derived_fields import compute_event_fields, enrich_event

fields = compute_event_fields(event)
# fields["allocator_gap_bytes"] always present
# fields["utilization_ratio"] is None when device_total_bytes is unknown

enriched = enrich_event(event)
# {"allocator_allocated_bytes": ..., ..., "allocator_gap_bytes": ..., ...}

Functions

compute_event_fields(event)	Compute row-scoped derived fields from a single telemetry event.
compute_session_fields(events)	Compute session-scoped rollups across an ordered sequence of events.
enrich_event(event)	Return a flat dict merging raw event fields with derived fields.

Classes

DerivedFields	Computed fields derived from a single telemetry event.
SessionDerivedFields	Session-scoped rollups computed across a sequence of events.

class stormlog.derived_fields.DerivedFields

Bases: TypedDict

Computed fields derived from a single telemetry event.

allocator_gap_bytes is always present. All other fields are present only when the underlying raw counters are available; their absence is encoded as None in the returned dict rather than a missing key.

allocator_gap_bytes: int

utilization_ratio: None | float

fragmentation_ratio: None | float

is_degraded_collector: bool

class stormlog.derived_fields.SessionDerivedFields

Bases: TypedDict

Session-scoped rollups computed across a sequence of events.

peak_utilization_ratio: None | float

avg_fragmentation_ratio: None | float

is_session_interrupted: bool

stormlog.derived_fields.compute_event_fields(event)

Compute row-scoped derived fields from a single telemetry event.

event may be a TelemetryEventV2, TelemetryEventV3, or any object / mapping that exposes the standard allocator counter attributes.

allocator_gap_bytes is always present in the returned dict. Fields that require raw counters which may be absent (e.g. device_total_bytes) are returned as None rather than being omitted.

Parameters:

event (Any) – A telemetry event object or mapping.

Returns:

A DerivedFields dict.

Return type:

DerivedFields

stormlog.derived_fields.compute_session_fields(events)

Compute session-scoped rollups across an ordered sequence of events.

Parameters:

events (Sequence[Any]) – Ordered sequence of telemetry event objects or mappings.

Returns:

• peak_utilization_ratio - highest per-event utilization seen; or None if device_total_bytes was unavailable in every event.

• avg_fragmentation_ratio - mean fragmentation ratio across events where allocator_reserved_bytes > 0; None if none qualify.

• is_session_interrupted - True when the last event is not a "stop" event.

Return type:

A SessionDerivedFields dict with

stormlog.derived_fields.enrich_event(event)

Return a flat dict merging raw event fields with derived fields.

Derived fields are nested under a "derived" key so that raw and computed fields never collide.

Parameters:

event (Any) – A telemetry event object or mapping.

Returns:

{"schema_version": ..., ..., "derived": {"allocator_gap_bytes": ..., ...}}

Return type:

Dict[str, Any]