Module telemetry 

Structured per-request API telemetry.

Opt-in via the telemetry config key (off | basic | full). Writes one JSON record per API call to ~/.cache/synaps/api-log.jsonl (mode 0600, O_NOFOLLOW — same hardening as the legacy usage log).

basic records timing, usage, an estimated cost_usd (from agent_core::pricing), the persisted conversation id (session_id, the ~/.synaps-cli/sessions/<id>.json id) and the request-trace correlation ids (runtime_session_id / turn_id / trace_request_id), so a record joins both its session and its request-trace.jsonl line. Worker records also carry the worker’s identity (worker_agent, worker_handle, parent_session_id, parent_runtime_session_id). After an automatic context rollover a record names its context window (rollover_window), and the window’s first request says rollover: true. full additionally records rate-limit headers. The cache_diag verdict is present at either level when cache_diagnostics is on.

Optional fields are omitted when unknown — never written as 0.

Writes are best-effort and non-blocking: persistence goes through the bounded background writer (Task 11, spec §6.5), so a slow or broken log path can never delay or fail the request pipeline. Failures are counted (never silent-and-invisible) with one warning per persistent failure class.

Re-exports

pub use writer::default_telemetry_log_path;

pub use writer::default_trace_log_path;

pub use writer::ShutdownOutcome;

pub use writer::TelemetryWriter;

pub use writer::WriteGate;

pub use writer::WriterOptions;

pub use writer::WriterStats;

pub use writer::WriterTraceSink;

pub use writer::DEFAULT_MAX_FILE_BYTES;

pub use writer::DEFAULT_MAX_GENERATIONS;

pub use writer::DEFAULT_QUEUE_CAPACITY;

pub use writer::DEFAULT_SHUTDOWN_FLUSH_TIMEOUT;

Modules

writer

Bounded, non-blocking background writer for observability persistence (Task 11, spec §6.5).

Structs

CacheDiagRecord

Cache-diagnostics result (beta cache-diagnosis-2026-04-07). Only present when the user opted in via cache_diagnostics = true.

ContextRecord

Request-shape context: what we sent, for correlating cache behavior.

RateLimitRecord

Rate-limit headroom captured from anthropic-ratelimit-* response headers. Only recorded at full level.

RecordStamp

Identity fields a TelemetryWriter handle stamps onto every record enqueued through it: the persisted conversation id of the session (see Runtime::request_telemetry) and, on worker handles, who the worker is (see WorkerTelemetry::worker_writer).

RolloverStamp

What a turn request tells its telemetry record about context rollover (see TelemetryRecord::rollover_window).

TelemetryRecord

One JSONL record per API call.

UsageRecord

Token usage for one API call, including the cache-creation TTL breakdown.

WorkerTelemetry

The parent session’s telemetry, handed to the subagents it spawns.

Enums

TelemetryLevel

Telemetry verbosity level, parsed from the telemetry config key.

Constants

RETRY_DELAY_CAP

Maximum delay we’ll honour from any rate-limit header. A pathological reset timestamp far in the future would otherwise stall the turn indefinitely.

Functions

ratelimit_from_headers

Extract rate-limit headroom from response headers.

request_id_from_headers

Extract the request-id response header.

retry_delay_from_headers

Compute how long to wait before the next retry, consulting response headers.