telemetry.enabled on without telemetry.endpoint set is a config error at
boot, not a silent no-op.
What is sent
When enabled, one small JSON document is POSTed to your configuredendpoint once
every intervalMinutes (never at boot, never before the first interval elapses):
installId— a random UUID generated on the first send (not at boot), stored incache.db. Not derived from your machine, your vault, or anything else identifying. Rotate it any time withreliquary-tc telemetry reset-id.toolCalls— counts keyed by tool name, but ONLY a registered tool name can become a key: atools/callnaming anything else (including a bug, or a hostile client probing with an arbitrary string) is counted under a single fixed key,"unknown", never under the caller’s own string.errorCodes— counts keyed by this server’s fixed, closed error-code taxonomy (e.g.acl_denied,throttled); anything that is not one of those codes is counted under"unknown"too, the same way.clientNames— up to 32 distinct, canonicalized client labels (the same small built-in table the deprecatedtoolFacade.mode: "auto"matches client names against — today"claude-code"/"cursor"); a client whose name doesn’t match anything in that table is counted under"other", never under its own raw, caller-supplied string.facadeMode— which tool surface (triad/domain/flat) this server is advertising.
toolCalls/errorCodes/clientNames are always empty in telemetry preview’s
output — this CLI command runs in its own short-lived process, which has observed no
tool calls at all. To see a RUNNING server’s real counts, read server_health’s
telemetry block or doctor’s report on that server instead.
telemetry preview --show-path additionally shows your endpoint’s path — off by
default, since a collector convention can also use the path as a credential (see
below).
What is never sent
Vault paths, note content, search queries, vault ids, principals/callers, tokens, hostnames, or environment variables. This is enforced structurally: the document is validated against a.strict() schema whose key set is closed — a field outside that
set fails validation and is never sent, not merely “not currently populated.” Within
toolCalls/errorCodes/clientNames, the same structural enforcement applies at the
KEY level, not just the top level — see the allowlisting described above. A
property-based test dispatches adversarial tool names (paths, URLs) through this
server’s real dispatch path — the exact route a hostile tools/call would take, not a
hand-built call into the counter directly — and asserts the resulting document never
contains a path separator, a scheme:// marker, or the caller’s raw string, at any
depth.
Enabling it
endpoint must be https:// unless the host is loopback (localhost /
127.0.0.1 / [::1]) — that carve-out exists for tests and for running a reference
collector locally, not for a production deployment. It also may not name a literal
private, link-local, carrier-grade-NAT, unspecified, or cloud-metadata IP address
(e.g. 192.168.x.x, 10.x.x.x, 169.254.169.254) — loopback is the one such range
that stays allowed. A hostname that happens to resolve to one of these at request
time is not checked (this is a config-time, literal-text check only, documented as
such — resolving DNS during config validation would need a network call and could
still differ from the address actually used at send time).
endpoint may not contain userinfo (https://user:pw@host/...) — a URL is
exactly what telemetry preview/status, doctor, and server_health print, and
what a failed send logs, so a credential placed there would leak. If your collector
needs authentication, set telemetry.authTokenEnv to the name of an environment
variable holding a bearer token — the document and that token both travel to your
collector, so endpoint still needs to be encrypted in transit; it is sent as an
Authorization: Bearer <value> header and never printed, logged, or persisted
anywhere. If authTokenEnv is set but the named variable is unset, the send is
refused (never sent unauthenticated) and reported in doctor/telemetry status.
intervalMinutes has a floor of 60 — this is aggregate, low-frequency telemetry, not
a heartbeat.
A send never blocks a tool call, never retries in a loop (one attempt per interval),
and never follows a redirect (which could otherwise resend your bearer token and the
document to an unaudited host). A failed send is logged once, at warn, with the
endpoint reduced to scheme://host — never the full URL — and the window’s counters
are kept (not reset) so the next attempt is cumulative rather than lossy.
Checking status
enabled / endpoint (redacted) / installId / intervalMinutes /
lastSendAt / lastError / nextSendAt. The same fields (minus intervalMinutes)
appear in doctor’s report and in server_health’s telemetry block, so a caller
doesn’t have to shell out to check them.
Turning it off
Settelemetry.enabled back to false (or remove the block — false is the
default). No further sends happen; installId and the last-send outcome stay on
disk (harmless local state) unless you also clear cache.db.