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 + cost. full additionally records rate-limit headers and cache-diagnostics results when available.

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::WriterOptions;

pub use writer::WriterStats;

pub use writer::WriterTraceSink;

pub use writer::DEFAULT_MAX_FILE_BYTES;

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.

TelemetryRecord

One JSONL record per API call.

UsageRecord

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

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.