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: a broken log path must never break the request pipeline. All errors are silently dropped (matching log_usage).

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.

Functions

ratelimit_from_headers

Extract rate-limit headroom from response headers.

request_id_from_headers

Extract the request-id response header.

write_record

Append a record to the telemetry log. Best-effort — all errors are silently dropped so a broken log path never breaks the request pipeline.