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.AttachmentFilter(session_id=None, job_id=None, rank=None, kind=None)[source]

Bases: object

Filters for external attachment sidecar rows.

Parameters:

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • kind (str | None)

session_id: str | None = None
job_id: str | None = None
rank: int | None = None
kind: str | None = None
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.CatalogRunEnvelope(run_id, path, title, description, job_id, started_at_ns, ended_at_ns, created_at_utc, updated_at_utc, source_namespace, source_ref, tags, sessions, attachments, metadata=<factory>)[source]

Bases: object

Manifest-backed top-level Stormlog run envelope.

Parameters:

  • run_id (str)

  • path (Path)

  • title (str | None)

  • description (str | None)

  • job_id (str | None)

  • started_at_ns (int | None)

  • ended_at_ns (int | None)

  • created_at_utc (str | None)

  • updated_at_utc (str | None)

  • source_namespace (str | None)

  • source_ref (str | None)

  • tags (tuple[str, ...])

  • sessions (tuple[CatalogRunSessionRef, ...])

  • attachments (tuple[CatalogRunAttachment, ...])

  • metadata (Mapping[str, Any])

run_id: str
path: Path
title: str | None
description: str | None
job_id: str | None
started_at_ns: int | None
ended_at_ns: int | None
created_at_utc: str | None
updated_at_utc: str | None
source_namespace: str | None
source_ref: str | None
tags: tuple[str, ...]
sessions: tuple[CatalogRunSessionRef, ...]
attachments: tuple[CatalogRunAttachment, ...]
metadata: Mapping[str, Any]
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.CorrelationEvidence(evidence_id, kind, title, session_id, job_id, rank, world_size, start_ns, end_ns, source_path, source_kind, metadata=<factory>, confidence='low', reasons=())[source]

Bases: object

One piece of evidence related to a correlation anchor.

Parameters:

  • evidence_id (str)

  • kind (str)

  • title (str)

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • world_size (int | None)

  • start_ns (int | None)

  • end_ns (int | None)

  • source_path (str)

  • source_kind (str)

  • metadata (Mapping[str, Any])

  • confidence (str)

  • reasons (tuple[str, ...])

evidence_id: str
kind: str
title: str
session_id: str | None
job_id: str | None
rank: int | None
world_size: int | None
start_ns: int | None
end_ns: int | None
source_path: str
source_kind: str
metadata: Mapping[str, Any]
confidence: str = 'low'
reasons: tuple[str, ...] = ()
as_dict()[source]

Serialize the evidence row to a JSON-safe dictionary.

Return type:

dict[str, Any]

class stormlog.query.CorrelationFilter(session_id=None, job_id=None, rank=None, scope='session', at_ns=None, record_id=None, window_ns=60000000000, kinds=(), limit=None)[source]

Bases: object

Filters and anchor selection for a correlation query.

Parameters:

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • scope (Literal['session', 'distributed'])

  • at_ns (int | None)

  • record_id (str | None)

  • window_ns (int)

  • kinds (tuple[str, ...])

  • limit (int | None)

session_id: str | None = None
job_id: str | None = None
rank: int | None = None
scope: Literal['session', 'distributed'] = 'session'
at_ns: int | None = None
record_id: str | None = None
window_ns: int = 60000000000
kinds: tuple[str, ...] = ()
limit: int | None = None
class stormlog.query.CorrelationResult(anchor, evidence=(), warnings=())[source]

Bases: object

Correlation query output anchored to a timestamp or telemetry record.

Parameters:
anchor: Mapping[str, Any]
evidence: Sequence[CorrelationEvidence] = ()
warnings: Sequence[str] = ()
as_dict()[source]

Serialize the result to a JSON-safe dictionary.

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.ExternalAttachment(title, kind, attachment_id, url, path, session_id, job_id, rank, start_ns, end_ns, created_at_utc, updated_at_utc, metadata, sidecar_path, run_id=None, storage=None, source_namespace=None, source_ref=None)[source]

Bases: object

External evidence discovered from a local attachment sidecar.

Parameters:

  • title (str)

  • kind (str)

  • attachment_id (str | None)

  • url (str | None)

  • path (str | None)

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • start_ns (int | None)

  • end_ns (int | None)

  • created_at_utc (str | None)

  • updated_at_utc (str | None)

  • metadata (Mapping[str, Any])

  • sidecar_path (str)

  • run_id (str | None)

  • storage (str | None)

  • source_namespace (str | None)

  • source_ref (str | None)

title: str
kind: str
attachment_id: str | None
url: str | None
path: str | None
session_id: str | None
job_id: str | None
rank: int | None
start_ns: int | None
end_ns: int | None
created_at_utc: str | None
updated_at_utc: str | None
metadata: Mapping[str, Any]
sidecar_path: str
run_id: str | None = None
storage: str | None = None
source_namespace: str | None = None
source_ref: str | None = None
as_dict()[source]

Serialize the attachment row to a JSON-safe dictionary.

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_runs(filters=None)[source]

Return explicit run envelopes or synthesized local run rows.

Parameters:

filters (RunFilter | None)

Return type:

list[RunRow]

list_run_attachments(filters=None)[source]

Return local, distributed, and external attachments indexed by run.

Parameters:

filters (RunAttachmentFilter | None)

Return type:

list[RunAttachmentRow]

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_attachments(filters=None)[source]

Return filtered external attachment sidecar rows.

Parameters:

filters (AttachmentFilter | None)

Return type:

list[ExternalAttachment]

correlate(filters)[source]

Return evidence related to a timestamp or telemetry record anchor.

Parameters:

filters (CorrelationFilter)

Return type:

CorrelationResult

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.RunAttachmentFilter(run_id=None, session_id=None, job_id=None, rank=None, kind=None, source_namespace=None, source_ref=None)[source]

Bases: object

Filters for run attachment catalog rows.

Parameters:

  • run_id (str | None)

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • kind (str | None)

  • source_namespace (str | None)

  • source_ref (str | None)

run_id: str | None = None
session_id: str | None = None
job_id: str | None = None
rank: int | None = None
kind: str | None = None
source_namespace: str | None = None
source_ref: str | None = None
class stormlog.query.RunAttachmentRow(run_id, title, kind, storage, attachment_id, url, path, session_id, job_id, rank, local_rank, world_size, start_ns, end_ns, source_path, source_kind, source_namespace, source_ref, metadata=<factory>)[source]

Bases: object

Query row for local, distributed, or external run evidence.

Parameters:

  • run_id (str)

  • title (str)

  • kind (str)

  • storage (Literal['reference', 'copy'])

  • attachment_id (str | None)

  • url (str | None)

  • path (str | None)

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • local_rank (int | None)

  • world_size (int | None)

  • start_ns (int | None)

  • end_ns (int | None)

  • source_path (str)

  • source_kind (str)

  • source_namespace (str | None)

  • source_ref (str | None)

  • metadata (Mapping[str, Any])

run_id: str
title: str
kind: str
storage: Literal['reference', 'copy']
attachment_id: str | None
url: str | None
path: str | None
session_id: str | None
job_id: str | None
rank: int | None
local_rank: int | None
world_size: int | None
start_ns: int | None
end_ns: int | None
source_path: str
source_kind: str
source_namespace: str | None
source_ref: str | None
metadata: Mapping[str, Any]
as_dict()[source]
Return type:

dict[str, Any]

class stormlog.query.RunFilter(run_id=None, session_id=None, job_id=None, rank=None, source_namespace=None, source_ref=None)[source]

Bases: object

Filters for top-level run envelope rows.

Parameters:

  • run_id (str | None)

  • session_id (str | None)

  • job_id (str | None)

  • rank (int | None)

  • source_namespace (str | None)

  • source_ref (str | None)

run_id: str | None = None
session_id: str | None = None
job_id: str | None = None
rank: int | None = None
source_namespace: str | None = None
source_ref: str | None = None
class stormlog.query.RunRow(run_id, explicit, title, description, job_id, started_at_ns, ended_at_ns, source_path, source_kind, source_namespace, source_ref, session_count, attachment_count, sessions, ranks, tags=(), metadata=<factory>)[source]

Bases: object

Query row describing one explicit or synthesized run envelope.

Parameters:

  • run_id (str)

  • explicit (bool)

  • title (str | None)

  • description (str | None)

  • job_id (str | None)

  • started_at_ns (int | None)

  • ended_at_ns (int | None)

  • source_path (str)

  • source_kind (str)

  • source_namespace (str | None)

  • source_ref (str | None)

  • session_count (int)

  • attachment_count (int)

  • sessions (tuple[str, ...])

  • ranks (tuple[int, ...])

  • tags (tuple[str, ...])

  • metadata (Mapping[str, Any])

run_id: str
explicit: bool
title: str | None
description: str | None
job_id: str | None
started_at_ns: int | None
ended_at_ns: int | None
source_path: str
source_kind: str
source_namespace: str | None
source_ref: str | None
session_count: int
attachment_count: int
sessions: tuple[str, ...]
ranks: tuple[int, ...]
tags: tuple[str, ...] = ()
metadata: Mapping[str, Any]
as_dict()[source]
Return type:

dict[str, Any]

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