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.

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.

TelemetryWriter

Cloneable handle to the bounded background writer.

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.

WriteGate

A gate the writer’s worker waits on before each job (WriterOptions::write_gate). Starts closed; open releases the worker for good.

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_MAX_GENERATIONS

Default rotated generations kept per log: one (<path>.1), the historical behaviour. Raised by the telemetry_log_generations config key.

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.