stormlog.telemetry_sink

Append-only telemetry sink with rollover and retention bounds.

Functions

read_telemetry_sink_manifest(path)

Read a sink manifest from a sink directory, manifest file, or segment file.

resolve_telemetry_sink_manifest_path(path)

Resolve a file or directory path to a sink manifest path, if present.

resolve_telemetry_sink_segment_paths(path)

Resolve append-only sink inputs to ordered JSONL segment paths.

Classes

AppendOnlyTelemetrySink(config)

Write telemetry records to newline-delimited JSON segments.

TelemetrySinkConfig(root_dir[, ...])

Runtime policy for append-only telemetry persistence.

TelemetrySinkManifest(schema_version, format)

Parsed append-only sink manifest with session ledger and segments.

TelemetrySinkSegment(filename, event_count, ...)

One JSONL segment tracked by the append-only sink manifest.
class stormlog.telemetry_sink.AppendOnlyTelemetrySink(config)[source]

Bases: object

Write telemetry records to newline-delimited JSON segments.

Parameters:

config (TelemetrySinkConfig)

start_session(summary=None)[source]

Register the active session for subsequent records.

Parameters:

summary (SessionSummary | None)

Return type:

SessionSummary

current_session()[source]

Return the active session summary, if any.

Return type:

SessionSummary | None

append(record)[source]
Parameters:

record (Mapping[str, Any])

Return type:

None

flush(force=False)[source]
Parameters:

force (bool)

Return type:

None

close(session_status='completed')[source]
Parameters:

session_status (str)

Return type:

None

get_diagnostics()[source]

Return runtime retention and rollover diagnostics.

Return type:

dict[str, int]

class stormlog.telemetry_sink.TelemetrySinkConfig(root_dir, flush_every_events=50, flush_every_seconds=2.0, rollover_max_bytes=67108864, rollover_max_events=10000, retention_max_files=8, retention_max_total_bytes=536870912)[source]

Bases: object

Runtime policy for append-only telemetry persistence.

Parameters:

  • root_dir (Path)

  • flush_every_events (int)

  • flush_every_seconds (float)

  • rollover_max_bytes (int)

  • rollover_max_events (int)

  • retention_max_files (int)

  • retention_max_total_bytes (int)

root_dir: Path
flush_every_events: int = 50
flush_every_seconds: float = 2.0
rollover_max_bytes: int = 67108864
rollover_max_events: int = 10000
retention_max_files: int = 8
retention_max_total_bytes: int = 536870912
class stormlog.telemetry_sink.TelemetrySinkManifest(schema_version, format, sessions=<factory>, segments=<factory>)[source]

Bases: object

Parsed append-only sink manifest with session ledger and segments.

Parameters:
schema_version: int
format: str
sessions: list[SessionSummary]
segments: list[TelemetrySinkSegment]
class stormlog.telemetry_sink.TelemetrySinkSegment(filename, event_count, size_bytes, closed, session_id=None)[source]

Bases: object

One JSONL segment tracked by the append-only sink manifest.

Parameters:

  • filename (str)

  • event_count (int)

  • size_bytes (int)

  • closed (bool)

  • session_id (str | None)

filename: str
event_count: int
size_bytes: int
closed: bool
session_id: str | None = None
stormlog.telemetry_sink.read_telemetry_sink_manifest(path)[source]

Read a sink manifest from a sink directory, manifest file, or segment file.

Parameters:

path (str | Path)

Return type:

TelemetrySinkManifest | None

stormlog.telemetry_sink.resolve_telemetry_sink_manifest_path(path)[source]

Resolve a file or directory path to a sink manifest path, if present.

Parameters:

path (str | Path)

Return type:

Path | None

stormlog.telemetry_sink.resolve_telemetry_sink_segment_paths(path)[source]

Resolve append-only sink inputs to ordered JSONL segment paths.

Parameters:

path (str | Path)

Return type:

list[Path]