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.

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.

TelemetryWriter

Cloneable handle to the bounded background writer.

UsageRecord

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

WriterOptions

Writer configuration. None paths resolve to the installation defaults.

WriterStats

Snapshot of the writer’s atomic counters.

WriterTraceSink

Production TraceSink: enqueues each record onto the shared writer.

Enums

ShutdownOutcome

Typed result of a bounded shutdown flush.

TelemetryLevel

Telemetry verbosity level, parsed from the telemetry config key.

Constants

DEFAULT_MAX_FILE_BYTES

Default per-file size cap before rotation (matches the legacy writer).

DEFAULT_QUEUE_CAPACITY

Default bounded queue capacity: deep enough that a briefly slow disk never drops records, small enough to bound memory (records are boxed).

DEFAULT_SHUTDOWN_FLUSH_TIMEOUT

Default budget for the shutdown flush at process-exit epilogues (Task 11): long enough for a healthy disk to drain a full queue, short enough that a hung filesystem can never stall a clean exit.

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

default_telemetry_log_path

Default telemetry log path: ~/.cache/synaps/api-log.jsonl.

default_trace_log_path

Default trace log path: ~/.cache/synaps/request-trace.jsonl.

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.