aeat.application.diagnostics_telemetry module

Remote-telemetry posture reporting and the dry-run-safe flush composition.

Wires the CLI surface promised by 2026-07-04-remote-telemetry-adr (GitHub issue #407) over the core telemetry package (telemetry) without re-implementing any of its gate, schema, or sink logic (composition-service-no-parallel-write-path):

  • build_telemetry_status_report() projects the current Settings posture (opt-in, tier, gestor mode, endpoint) plus whether an emission would currently be permitted, so an operator can inspect the deployment’s telemetry posture without guessing at environment variable names.

  • build_telemetry_flush_preview() aggregates the same local, non-sensitive LLM run-timing signal build_run_health_report() already reads (LLMRunTelemetryRecorder) into ONE allowlisted TelemetryEventPayload via build_telemetry_payload(), and reports whether the consent gate (telemetry_emit_permitted()) would currently permit sending it. This function never sends anything: it is the --dry-run preview surface. build_telemetry_flush_preview is also the payload-construction step the real (non-dry-run) flush reuses, so preview and send can never observe a different payload shape.

  • flush_telemetry() performs the real send: it reuses the identical preview payload, re-checks the consent gate, and – only when both the gate permits AND an endpoint is configured – hands the payload to a real HttpTelemetrySink. When the gate refuses or no endpoint is configured, it is a pure no-op (mirroring emit_telemetry_event()’s own no-op contract), so calling this function is always safe regardless of posture.

No producer here reads transaction content, profile identity, or file contents; the aggregate is built from the same accounting/timing-only LLMRunRecord rows the local-only run-health diagnostics already expose.

See also

telemetry

Consent gate, closed payload schema, workspace hash, and optional HTTP sink reused by this application service.

build_run_health_report()

Local-only LLM run accounting source aggregated by the flush preview.

_app_diagnostics_telemetry

CLI transport that exposes status and dry-run-safe flush commands.

TelemetryEventPayload

Closed allowlisted payload shape built by preview and reused by send.

class TelemetryStatusReport(**data)[source]

Bases: BaseModel

The deployment’s current remote-telemetry posture.

Projects the raw Settings telemetry fields plus the derived would_emit verdict a hypothetical fully-acknowledged invocation would currently receive from telemetry_emit_permitted(). Never triggers an emission; this is a read-only report.

Parameters:
opt_in: bool
tier: TelemetryTier
gestor_mode: bool
endpoint: str | None
would_emit_if_acknowledged: bool
class TelemetryFlushPreview(**data)[source]

Bases: BaseModel

The payload a flush would send, plus whether it would currently send at all.

payload is the exact allowlisted TelemetryEventPayload flush_telemetry() would hand to the sink; gate_permits and would_send are evaluated against the SAME acknowledged value the caller supplied (never hardcoded to True), so a preview built without an acknowledgement honestly reports “would not currently send” even when opt-in, tier, and endpoint are otherwise fully configured. would_send folds the consent-gate verdict with whether an endpoint is configured, so a dry-run preview can honestly report “built, but would not transmit” (refused consent, or no endpoint) versus “would transmit”.

Parameters:
payload: TelemetryEventPayload
gate_permits: bool
endpoint_configured: bool
would_send: bool
build_telemetry_status_report(*, settings=None)[source]

Report the current remote-telemetry consent posture.

Parameters:

settings (Settings | None) – Resolved deployment settings; defaults to load_settings().

Return type:

TelemetryStatusReport

Returns:

The populated TelemetryStatusReport.

build_telemetry_flush_preview(*, settings=None, acknowledged=False)[source]

Build the allowlisted payload a flush would send, without sending it.

Aggregates every locally recorded LLM run (LLMRunRecord, read via build_run_health_report()) into one diagnostics.llm_run TelemetryEventPayload. This is the sole payload-construction step; both the --dry-run preview and the real flush_telemetry() call this function so they can never observe a different payload shape.

gate_permits/would_send are evaluated against acknowledged exactly as supplied – defaulting to False (the honest state of a bare --dry-run invocation with no acknowledgement flag), never hardcoded to True. This mirrors telemetry_emit_permitted()’s own never-sticky per-invocation acknowledgement contract.

Parameters:

  • settings (Settings | None) – Resolved deployment settings; defaults to load_settings().

  • acknowledged (bool) – Whether the operator acknowledged remote telemetry for this specific invocation. Never sticky.

Return type:

TelemetryFlushPreview

Returns:

The populated TelemetryFlushPreview. Never performs a network call.

flush_telemetry(*, settings=None, acknowledged)[source]

Send the aggregate local telemetry payload, honouring the consent gate.

Reuses build_telemetry_flush_preview() (with the SAME acknowledged value) for payload construction and verdict computation, so the returned report always reflects the real invocation’s acknowledgement – never a hardcoded optimistic verdict. Delegates the actual gate check and dispatch to emit_telemetry_event() (composition-service-no-parallel-write-path): this function never re-implements the consent gate or the HTTP transport.

A real send requires ALL of: the consent gate permits (deployment opt-in, non-off tier, gestor mode off) AND acknowledged is True for THIS invocation (never sticky) AND settings.aeat_telemetry_endpoint is configured. Any missing condition makes this call a pure no-op – nothing is sent – mirroring emit_telemetry_event()’s own no-op contract.

Parameters:

  • settings (Settings | None) – Resolved deployment settings; defaults to load_settings().

  • acknowledged (bool) – Whether the operator acknowledged remote telemetry for this specific invocation. Never sticky; must be re-affirmed on every call.

Return type:

TelemetryFlushPreview

Returns:

The TelemetryFlushPreview reflecting exactly what was (or, because a condition was refused, would have been) sent for THIS invocation’s acknowledged value.