Snapshot-Ready Telemetry Summaries

A tiny telemetry helper that returns normalized summaries and binary thumbnails that must be verified with snapshot assertions configured per comparison.

Capabilities

Normalizes summaries with dynamic metadata

• Calling prepare_summary with a reading containing metrics, tags, and optional trace data returns a summary with id, sorted metrics, numeric stats (min, max, avg), and metadata containing a freshly generated ISO-8601 generated_at value and a unique nonce; validations must tolerate the per-call time/nonce while keeping the surrounding structure stable @test

Filters internal fields on demand

• When include_internal is false, the summary omits any diagnostics; when true, it includes a debug block with the capture timestamp and the original trace entries without changing the public portion of the summary (id, metrics, stats, tags) @test

Emits binary thumbnail bytes

• render_thumbnail produces deterministic bytes starting with a short ASCII header describing the reading, requested size, and metric stats so the output can be stored as a binary snapshot using a non-text extension @test

Implementation

@generates

API

from typing import Iterable, Mapping, Any, Tuple

def prepare_summary(reading: Mapping[str, Any], include_internal: bool = False) -> dict:
    """
    Build a normalized summary of a telemetry reading.
    - Required keys: id (str), metrics (mapping of str to number), tags (mapping of str to str)
    - Output must include sorted metrics, min/max/avg stats, original tags, and metadata with generated_at ISO-8601 timestamp and nonce string unique per call.
    - When include_internal is True, include a debug block with captured_at timestamp and a trace list preserving the order provided in reading.get("trace", []) without altering the public summary data.
    """

def render_thumbnail(reading_id: str, metrics: Iterable[float], size: Tuple[int, int] = (64, 64)) -> bytes:
    """
    Produce binary thumbnail bytes summarizing the reading, size, and basic stats.
    Content must start with an ASCII header, remain deterministic for identical inputs, and include width x height info.
    """

Dependencies { .dependencies }

Syrupy snapshotting { .dependency }

Snapshot testing library used to assert structured data and binary payloads with per-assert match configuration, filters, and extension selection.