stormlog.query

Local query API for Stormlog artifact directories and telemetry files.

Functions

open(paths)

Open one or more local artifact paths for in-process querying.

Classes

`ArtifactCatalog`(paths)	Manifest-first catalog of local Stormlog artifacts.
`CatalogOOMBundle`(bundle_path, manifest_path, ...)	Manifest-backed OOM dump bundle discovered during cataloging.
`CatalogSource`(path, source_kind[, ...])	One discovered source of queryable artifact data.
`CatalogWarning`(path, message)	Non-fatal discovery or loading warning.
`EventFilter`([session_id, event_type, rank, ...])	Filters for canonical telemetry event rows.
`EventRow`(event, source_path, source_kind, ...)	Query row wrapping a canonical telemetry event and provenance.
`IssueFilter`([fingerprint_id, kind, state, ...])	Filters for grouped issue rows.
`OOMBundleFilter`([session_id, backend, ...])	Filters for OOM bundle rows.
`OOMBundleRow`(bundle_path, created_at_utc, ...)	Query row for one OOM bundle manifest.
`QueryStore`(catalog)	Reusable local query surface over Stormlog artifacts.
`SessionFilter`([session_id, status, job_id, ...])	Filters for catalog/session rows.
`SessionRow`(session_id, status, ...)	Query row describing one loaded or manifest-backed session.
`SummaryRow`(metric, group_by, value[, ...])	Built-in summary result row.

class stormlog.query.ArtifactCatalog(paths)[source]

Bases: object

Manifest-first catalog of local Stormlog artifacts.

Parameters:: paths (Sequence[str | Path])

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.CatalogOOMBundle(bundle_path, manifest_path, created_at_utc, backend, reason, event_count, session_id, session_status, exception_type=None, exception_module=None)[source]

Bases: object

Manifest-backed OOM dump bundle discovered during cataloging.

Parameters:

bundle_path (Path)
manifest_path (Path)
created_at_utc (str | None)
backend (str | None)
reason (str | None)
event_count (int | None)
session_id (str | None)
session_status (str | None)
exception_type (str | None)
exception_module (str | None)

bundle_path: Path

manifest_path: Path

created_at_utc: str | None

backend: str | None

reason: str | None

event_count: int | None

session_id: str | None

session_status: str | None

exception_type: str | None = None

exception_module: str | None = None

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.CatalogSource(path, source_kind, event_paths=(), manifest_path=None)[source]

Bases: object

One discovered source of queryable artifact data.

Parameters:

path (Path)
source_kind (Literal['sink', 'telemetry_json', 'telemetry_jsonl', 'telemetry_csv', 'diagnose_bundle', 'oom_bundle'])
event_paths (tuple[Path, ...])
manifest_path (Path | None)

path: Path

source_kind: Literal['sink', 'telemetry_json', 'telemetry_jsonl', 'telemetry_csv', 'diagnose_bundle', 'oom_bundle']

event_paths: tuple[Path, ...] = ()

manifest_path: Path | None = None

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.CatalogWarning(path, message)[source]

Bases: object

Non-fatal discovery or loading warning.

Parameters:

path (str)
message (str)

path: str

message: str

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.EventFilter(session_id=None, event_type=None, rank=None, collector=None, status=None, time_start_ns=None, time_end_ns=None, has_alert=None, collector_health_status=None, backend=None, limit=None)[source]

Bases: object

Filters for canonical telemetry event rows.

Parameters:

session_id (str | None)
event_type (str | None)
rank (int | None)
collector (str | None)
status (str | None)
time_start_ns (int | None)
time_end_ns (int | None)
has_alert (bool | None)
collector_health_status (str | None)
backend (str | None)
limit (int | None)

session_id: str | None = None

event_type: str | None = None

rank: int | None = None

collector: str | None = None

status: str | None = None

time_start_ns: int | None = None

time_end_ns: int | None = None

has_alert: bool | None = None

collector_health_status: str | None = None

backend: str | None = None

limit: int | None = None

class stormlog.query.EventRow(event, source_path, source_kind, session_status)[source]

Bases: object

Query row wrapping a canonical telemetry event and provenance.

Parameters:

event (TelemetryEventV3)
source_path (str)
source_kind (str)
session_status (str)

event: TelemetryEventV3

source_path: str

source_kind: str

session_status: str

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.IssueFilter(fingerprint_id=None, kind=None, state=None, severity=None, session_id=None)[source]

Bases: object

Filters for grouped issue rows.

Parameters:

fingerprint_id (str | None)
kind (Literal['oom', 'collector_degradation', 'alert', 'hidden_memory_anomaly'] | None)
state (Literal['open', 'resolved', 'ignored', 'regressed'] | None)
severity (str | None)
session_id (str | None)

fingerprint_id: str | None = None

kind: Literal['oom', 'collector_degradation', 'alert', 'hidden_memory_anomaly'] | None = None

state: Literal['open', 'resolved', 'ignored', 'regressed'] | None = None

severity: str | None = None

session_id: str | None = None

class stormlog.query.OOMBundleFilter(session_id=None, backend=None, reason=None, created_after=None, created_before=None)[source]

Bases: object

Filters for OOM bundle rows.

Parameters:

session_id (str | None)
backend (str | None)
reason (str | None)
created_after (str | None)
created_before (str | None)

session_id: str | None = None

backend: str | None = None

reason: str | None = None

created_after: str | None = None

created_before: str | None = None

class stormlog.query.OOMBundleRow(bundle_path, created_at_utc, backend, reason, event_count, session_id, session_status, exception_type, exception_module)[source]

Bases: object

Query row for one OOM bundle manifest.

Parameters:

bundle_path (str)
created_at_utc (str | None)
backend (str | None)
reason (str | None)
event_count (int | None)
session_id (str | None)
session_status (str | None)
exception_type (str | None)
exception_module (str | None)

bundle_path: str

created_at_utc: str | None

backend: str | None

reason: str | None

event_count: int | None

session_id: str | None

session_status: str | None

exception_type: str | None

exception_module: str | None

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.QueryStore(catalog)[source]

Bases: object

Reusable local query surface over Stormlog artifacts.

Parameters:: catalog (ArtifactCatalog)

list_sessions(filters=None)[source]

Return session rows from manifest metadata or loaded flat files.

Parameters:: filters (SessionFilter | None)
Return type:: list[SessionRow]

query_events(filters=None)[source]

Return filtered canonical telemetry event rows.

Parameters:: filters (EventFilter | None)
Return type:: list[EventRow]

list_oom_bundles(filters=None)[source]

Return filtered OOM bundle rows.

Parameters:: filters (OOMBundleFilter | None)
Return type:: list[OOMBundleRow]

list_issues(filters=None, *, state_overrides=None)[source]

Return grouped issues derived from discovered artifacts.

Parameters:

filters (IssueFilter | None)
state_overrides (Mapping[str, str] | None)

Return type:

list[StormlogIssue]

summarize(metric, *, group_by=None)[source]

Run one built-in summary query.

Parameters:

metric (Literal['session_count_by_status', 'peak_allocator_allocated_bytes', 'peak_allocator_reserved_bytes', 'peak_device_used_bytes', 'alert_count', 'collector_degradation_transitions', 'interrupted_sessions_with_oom_bundles', 'hidden_memory_gap_growth'])
group_by (Literal['session', 'session-rank', 'rank', 'status'] | None)

Return type:

list[SummaryRow]

class stormlog.query.SessionFilter(session_id=None, status=None, job_id=None, rank=None, world_size=None, has_oom_bundle=None, source_kind=None)[source]

Bases: object

Filters for catalog/session rows.

Parameters:

session_id (str | None)
status (str | None)
job_id (str | None)
rank (int | None)
world_size (int | None)
has_oom_bundle (bool | None)
source_kind (str | None)

session_id: str | None = None

status: str | None = None

job_id: str | None = None

rank: int | None = None

world_size: int | None = None

has_oom_bundle: bool | None = None

source_kind: str | None = None

class stormlog.query.SessionRow(session_id, status, started_at_ns, ended_at_ns, host, pid, job_id, rank, local_rank, world_size, source, source_path, source_kind, source_count, warning_count, event_count, oom_bundle_count)[source]

Bases: object

Query row describing one loaded or manifest-backed session.

Parameters:

session_id (str)
status (str)
started_at_ns (int)
ended_at_ns (int | None)
host (str)
pid (int)
job_id (str | None)
rank (int)
local_rank (int)
world_size (int)
source (str)
source_path (str)
source_kind (str)
source_count (int)
warning_count (int)
event_count (int | None)
oom_bundle_count (int)

session_id: str

status: str

started_at_ns: int

ended_at_ns: int | None

host: str

pid: int

job_id: str | None

rank: int

local_rank: int

world_size: int

source: str

source_path: str

source_kind: str

source_count: int

warning_count: int

event_count: int | None

oom_bundle_count: int

as_dict()[source]

Return type:: dict[str, Any]

class stormlog.query.SummaryRow(metric, group_by, value, session_id=None, rank=None, status=None, details=<factory>)[source]

Bases: object

Built-in summary result row.

Parameters:

metric (str)
group_by (str)
value (int | float | str | None)
session_id (str | None)
rank (int | None)
status (str | None)
details (Mapping[str, Any])

metric: str

group_by: str

value: int | float | str | None

session_id: str | None = None

rank: int | None = None

status: str | None = None

details: Mapping[str, Any]

as_dict()[source]

Return type:: dict[str, Any]

stormlog.query.open(paths)[source]

Open one or more local artifact paths for in-process querying.

Parameters:: paths (Sequence[str | Path])
Return type:: QueryStore