stormlog.issues

Durable issue fingerprints and grouped issue row models.

Functions

categorize_alert_context(context)

Return a stable alert category from event context text.

freeze_dimensions(dimensions)

Return a recursively immutable canonical dimension mapping.

json_safe_dimensions(dimensions)

Return a mutable JSON-safe copy of canonical dimension material.

normalize_dimensions(dimensions)

Normalize fingerprint dimensions into a canonical JSON-safe mapping.

normalize_issue_state(state)

Validate and normalize an issue state string.

normalize_text_dimension(value, *[, default])

Return a low-cardinality text token for fingerprint dimensions.

normalized_error_stem(error)

Return a stable low-cardinality error stem.

Classes

IssueEvidenceLink([session_id, ...])

Link from a grouped issue back to raw session, event, or bundle evidence.

IssueFingerprint(kind, dimensions[, ...])

Stable grouping identity for recurring Stormlog issues.

StormlogIssue(fingerprint, title, severity, ...)

Grouped issue suitable for CLI/TUI presentation and future persistence.

Bases: object

Link from a grouped issue back to raw session, event, or bundle evidence.

Parameters:

  • session_id (str | None)

  • timestamp_ns (int | None)

  • rank (int | None)

  • source_path (str | None)

  • source_kind (str | None)

  • event_type (str | None)

  • bundle_path (str | None)

  • metadata (Mapping[str, Any])

session_id: str | None = None
timestamp_ns: int | None = None
rank: int | None = None
source_path: str | None = None
source_kind: str | None = None
event_type: str | None = None
bundle_path: str | None = None
metadata: Mapping[str, Any]
as_dict()[source]

Serialize the evidence link into a JSON-safe mapping.

Return type:

dict[str, Any]

class stormlog.issues.IssueFingerprint(kind, dimensions, schema_version=1)[source]

Bases: object

Stable grouping identity for recurring Stormlog issues.

Parameters:

  • kind (Literal['oom', 'collector_degradation', 'alert', 'hidden_memory_anomaly'])

  • dimensions (Mapping[str, Any])

  • schema_version (int)

kind: Literal['oom', 'collector_degradation', 'alert', 'hidden_memory_anomaly']
dimensions: Mapping[str, Any]
schema_version: int = 1
property fingerprint_id: str

Return a deterministic hash for this fingerprint.

as_dict()[source]

Serialize the fingerprint into a JSON-safe mapping.

Return type:

dict[str, Any]

class stormlog.issues.StormlogIssue(fingerprint, title, severity, hit_count, first_seen_ns, last_seen_ns, affected_sessions, representative_evidence, evidence, state='open', details=<factory>)[source]

Bases: object

Grouped issue suitable for CLI/TUI presentation and future persistence.

Parameters:

  • fingerprint (IssueFingerprint)

  • title (str)

  • severity (str)

  • hit_count (int)

  • first_seen_ns (int | None)

  • last_seen_ns (int | None)

  • affected_sessions (Sequence[str])

  • representative_evidence (IssueEvidenceLink)

  • evidence (Sequence[IssueEvidenceLink])

  • state (Literal['open', 'resolved', 'ignored', 'regressed'])

  • details (Mapping[str, Any])

fingerprint: IssueFingerprint
title: str
severity: str
hit_count: int
first_seen_ns: int | None
last_seen_ns: int | None
affected_sessions: Sequence[str]
representative_evidence: IssueEvidenceLink
evidence: Sequence[IssueEvidenceLink]
state: Literal['open', 'resolved', 'ignored', 'regressed'] = 'open'
details: Mapping[str, Any]
property fingerprint_id: str

Return the issue fingerprint id.

property kind: Literal['oom', 'collector_degradation', 'alert', 'hidden_memory_anomaly']

Return the issue kind.

as_dict()[source]

Serialize the grouped issue into a JSON-safe mapping.

Return type:

dict[str, Any]

stormlog.issues.categorize_alert_context(context)[source]

Return a stable alert category from event context text.

Parameters:

context (object)

Return type:

str

stormlog.issues.freeze_dimensions(dimensions)[source]

Return a recursively immutable canonical dimension mapping.

Parameters:

dimensions (Mapping[str, Any])

Return type:

Mapping[str, Any]

stormlog.issues.json_safe_dimensions(dimensions)[source]

Return a mutable JSON-safe copy of canonical dimension material.

Parameters:

dimensions (Mapping[str, Any])

Return type:

dict[str, Any]

stormlog.issues.normalize_dimensions(dimensions)[source]

Normalize fingerprint dimensions into a canonical JSON-safe mapping.

Parameters:

dimensions (Mapping[str, Any])

Return type:

dict[str, Any]

stormlog.issues.normalize_issue_state(state)[source]

Validate and normalize an issue state string.

Parameters:

state (str)

Return type:

Literal[‘open’, ‘resolved’, ‘ignored’, ‘regressed’]

stormlog.issues.normalize_text_dimension(value, *, default='unknown')[source]

Return a low-cardinality text token for fingerprint dimensions.

Parameters:

  • value (object)

  • default (str)

Return type:

str

stormlog.issues.normalized_error_stem(error)[source]

Return a stable low-cardinality error stem.

Parameters:

error (object)

Return type:

str