aeat.core.telemetry._schema module

Closed remote-telemetry metric-key registry and the allowlisted payload.

Every telemetry emission is shaped by TelemetryEventPayload, a pydantic model whose field set IS the entire content allowlist: there is no extra passthrough, no free-text message/context field, and no string field wide enough to carry operator-controlled financial or identity content. A producer’s counters and timings are validated against TELEMETRY_METRIC_REGISTRY — a closed, code-authored mapping from command dotted-path to its declared metric keys — so an unregistered key raises TelemetrySchemaError rather than silently passing through, and a registered-but-not-remote_allowed key is silently dropped from the outgoing payload (it may still exist for local-only diagnostics; it is simply never remote-eligible).

Extending the registry is a deliberate, reviewable code change — adding a new command’s schema entry, or flipping a key’s remote_allowed — never an implicit consequence of adding a new local metric elsewhere in the codebase.

See also

build_telemetry_payload()

Validates producers against this registry before emission.

emit_telemetry_event()

The only remote-eligible dispatch point for a validated payload.

class CounterSpec(**data)[source]

Bases: BaseModel

Declared shape of one counter metric key.

Variables:

  • description – Short, non-sensitive description of what the counter measures (e.g. "invocation count"). Never operator content.

  • remote_allowed – Whether this counter is eligible for remote transmission at all. False keeps the key local-only even when the deployment opts into remote telemetry.

Parameters:

  • description (str)

  • remote_allowed (bool)

description: str
remote_allowed: bool
class TimingSpec(**data)[source]

Bases: BaseModel

Declared shape of one timing metric key (milliseconds).

Variables:

  • description – Short, non-sensitive description of what the timing measures.

  • remote_allowed – Whether this timing is eligible for remote transmission at all.

Parameters:

  • description (str)

  • remote_allowed (bool)

description: str
remote_allowed: bool
class MetricSchema(**data)[source]

Bases: BaseModel

Closed declaration of the counters and timings one command may emit.

Variables:

  • command – Dotted-path command identifier the schema governs (e.g. "diagnostics.run_health"). Matches command.

  • counters – Closed mapping of counter key -> CounterSpec.

  • timings_ms – Closed mapping of timing key -> TimingSpec.

Parameters:
command: str
counters: Mapping[str, CounterSpec]
timings_ms: Mapping[str, TimingSpec]
class TelemetryEventPayload(**data)[source]

Bases: BaseModel

The one and only shape a telemetry emission may take.

This model’s field set IS the transmission allowlist. There is no extra field (model_config forbids it), no free-text field wide enough to carry a NIF, a transaction description, a file path, or any other operator-controlled content, and no nested nesting depth that could smuggle an unvetted payload through. error_kind is a short closed label (e.g. "timeout", "validation_error"), never raw exception text.

Variables:

  • schema_version – Payload schema version, for forward compatibility.

  • workspace_hash – Stable pseudonymous identifier for the local deployment (never the operator’s NIF or profile id).

  • command – The dotted-path metric-schema key this event belongs to.

  • counters – Emitted counter values, restricted to keys registered as remote_allowed for command.

  • timings_ms – Emitted timing values (milliseconds), restricted the same way.

  • succeeded – Whether the measured operation succeeded.

  • error_kind – Optional short closed error-kind label when succeeded is False.

  • captured_at – ISO-8601 UTC capture timestamp.

Parameters:
schema_version: int
workspace_hash: str
command: str
counters: Mapping[str, int]
timings_ms: Mapping[str, int]
succeeded: bool
error_kind: str | None
captured_at: str
TELEMETRY_METRIC_REGISTRY: Mapping[str, MetricSchema]

Closed command -> MetricSchema registry.

Every entry declares only non-sensitive operational counters/timings: CLI command-invocation counts and duration, local-LLM-run counts and duration, and error-kind occurrence frequency. error_kind on TelemetryEventPayload is always a short closed label (an exception class name such as "LLMClassifierError", mirroring error_kind) – never raw exception text, a file path, a NIF, or any other operator-controlled content. No entry here declares a counter/timing keyed by anything financial, personal, or free-text; extending this registry with such a key is refused structurally by TelemetryEventPayload’s extra="forbid" allowlist regardless of what a producer attempts to pass.

build_telemetry_payload(*, workspace_hash, command, counters=None, timings_ms=None, succeeded, error_kind=None, captured_at, registry=None)[source]

Build an allowlisted payload for command.

Validates every counter/timing key against TELEMETRY_METRIC_REGISTRY: a key that is not declared for command at all raises TelemetrySchemaError (an authoring error – the producer must register the key first); a key that IS declared but not remote_allowed is silently dropped from the returned payload (it stays a valid local-only metric; it is simply never remote-eligible).

Parameters:

  • workspace_hash (str) – Stable pseudonymous local-deployment identifier.

  • command (str) – Dotted-path metric-schema key.

  • counters (Mapping[str, int] | None) – Raw counter values keyed by metric name.

  • timings_ms (Mapping[str, int] | None) – Raw timing values (milliseconds) keyed by metric name.

  • succeeded (bool) – Whether the measured operation succeeded.

  • error_kind (str | None) – Optional short closed error-kind label.

  • captured_at (str) – ISO-8601 UTC capture timestamp.

  • registry (Mapping[str, MetricSchema] | None) – Metric-schema registry to validate against. Defaults to the production TELEMETRY_METRIC_REGISTRY; tests may inject a substitute registry to exercise the validation contract without depending on production entries.

Return type:

TelemetryEventPayload

Returns:

The allowlisted TelemetryEventPayload, carrying only registered, remote_allowed counter/timing keys.

Raises:

TelemetrySchemaError – When a counter or timing key is not declared in the command’s MetricSchema at all.