cadrumo.core.telemetry.emit module

The single remote-telemetry emit call site.

emit_telemetry_event() is the ONLY function a producer calls to emit a remote-eligible telemetry event. It composes the consent gate (telemetry_emit_permitted()) with a pluggable TelemetrySink; when the gate refuses, emission is a pure no-op – nothing is constructed, nothing is written, nothing is sent.

LocalNoopTelemetrySink, deliberately does nothing observable: it exists so callers and tests can exercise the full gate-then-emit sequence without a real transport, proving the payload a network sink would send is already the allowlisted, scrubbed shape.

See also

build_telemetry_payload()

Constructs the allowlisted payload consumed here.

HttpTelemetrySink

Optional network transport that implements the same sink protocol.

class TelemetrySink(*args, **kwargs)

Bases: Protocol

A destination for an allowlisted TelemetryEventPayload.

Implementations of this protocol are the only place a telemetry payload can leave this function’s caller. LocalNoopTelemetrySink transmits nothing over the network; HttpTelemetrySink implements the same protocol for a call site that opts into real transmission.

send(payload)

Deliver payload to this sink’s destination.

Return type:

None

Parameters:

payload (TelemetryEventPayload)

class LocalNoopTelemetrySink

Bases: object

A sink that intentionally does nothing.

Used as the default sink: the safe default is to accept the already-gated, already-allowlisted payload and discard it. This lets emit_telemetry_event() be called end-to-end (gate, schema validation, sink dispatch) without any observable network or disk side effect.

send(payload)

Discard payload. Deliberately a no-op.

Return type:

None

Parameters:

payload (TelemetryEventPayload)

emit_telemetry_event(payload, *, settings, acknowledged, sink=None)

Emit payload to sink if and only if the consent gate permits it.

Parameters:

• payload (TelemetryEventPayload) – The already-constructed, already-allowlisted TelemetryEventPayload (build it with build_telemetry_payload() so its counters/timings are schema-validated).

• settings (Settings) – Resolved deployment settings.

• acknowledged (bool) – Whether the operator acknowledged remote telemetry for this specific invocation. Never sticky; re-affirm at every call site.

• sink (TelemetrySink | None) – The destination to hand the payload to when permitted. Defaults to LocalNoopTelemetrySink (no caller opts into HttpTelemetrySink here).

Return type:

bool

Returns:

True when the event was handed to the sink; False when the consent gate refused and emission was a no-op.