Telemetry gating, environment, and deployment
Overview
This area owns the privacy gates and runtime classifiers that decide whether telemetry may proceed and how sent rows describe their runtime. mods/…/register.ts wires the pieces into the engine: the first hook on telemetry.* calls Gate.served from mods/…/served.ts, and its catch handler calls Gate.caught from mods/…/caught.ts. Only calls whose next.origin.tier is in SERVED_TIERS (builtin or core, from mods/…/served-tiers.ts) are passed down to the telemetry implementation; other tiers receive the REFUSED sentinel from mods/…/refused.ts. A missing origin tier is treated as a malformed host call and throws, but the catch hook converts a pre-continuation gate failure into the same refusal. If the continuation had already been called, caught replays it so lower hook failures are preserved rather than rewritten as gate refusals.
Telemetry collection can still be stopped later at send time. mods/…/register.ts builds the Environment object by reading USER_TYPE, NODE_ENV, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DO_NOT_TRACK, CLAUDE_CODE_CUSTOM_OAUTH_URL, CLAUDE_CODE_USE_GATEWAY, CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST, and the provider switches for Bedrock, Vertex, Foundry, Anthropic AWS, Anthropic Google Cloud, and Mantle. mods/…/telemetry-of.ts calls deps.environment() and deps.policy() before priming context and before each batch send, then passes them to mods/…/is-analytics-off.ts. If this check returns true, or if reading those inputs throws, context is not gathered for priming and queued rows are not sent.
isAnalyticsOff mirrors the CLI privacy rules with two small value interpreters. mods/…/is-env-set.ts treats any non-empty string as set, so DISABLE_TELEMETRY=0 and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0 still disable telemetry. mods/…/is-env-truthy.ts treats trimmed, case-insensitive 1, true, yes, and on as true. Analytics is off when NODE_ENV is test, either disable variable is set, DO_NOT_TRACK is truthy, a third-party provider switch is truthy without CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST being truthy, gateway mode is indicated by CLAUDE_CODE_USE_GATEWAY or managed policy pins, or CLAUDE_CODE_CUSTOM_OAUTH_URL is non-empty after trimming. When sending is allowed, telemetry-of.ts still uses environment.userType to label batches as ant only for USER_TYPE=ant; all other values are sent as external.
Deployment probing feeds row context rather than the privacy gate. mods/…/register.ts supplies deps.deployment() as a list of [deploymentName, signalHeld] pairs, using the same isEnvSet and isEnvTruthy helpers plus exact-value checks such as AWS_EXECUTION_ENV === AWS_ECS_FARGATE and an APP_URL suffix check for DigitalOcean App Platform. The canonical priority order lives in mods/…/deployments.ts; mods/…/deployment-of.ts returns the first deployment in that order whose signal is present, or unknown-<platform> when none match. mods/…/environment-fields-of.ts writes that result into the row's deploymentEnvironment field during context shaping. File-based deployment signals, currently described by mods/…/linux-files.ts as EC2 and Docker signals, share the same DeploymentSignal tuple type from mods/…/deployment-signal.ts and are merged into the probe before deploymentOf is applied.
Coverage and routing
This document owns:
mods/telemetry/hooks/is-analytics-off/**— analytics-off decision and environment value parsing.mods/telemetry/hooks/gate/**—telemetry.*served-tier gate, refusal sentinel, and catch behavior.mods/telemetry/hooks/environment/**—Environmentshape consumed by the send-time privacy gate.mods/telemetry/hooks/deployment/**— deployment names, signal tuple type, priority order, and deployment selection.
Coupling
- If any analytics-off environment variable is added, renamed, or its semantics change in mods/…/is-analytics-off.ts, also update the reader in mods/…/register.ts and the
Environmenttype in mods/…/environment.ts; telemetry-of.ts only sees the already-shapedEnvironment, so a missing field silently leaves telemetry enabled for that condition. - If changing truthiness or set-ness in mods/…/is-env-set.ts or mods/…/is-env-truthy.ts, check both privacy gating and context/deployment callers. register.ts uses
isEnvSetto record presence-only facts such as session tokens and terminal markers, while deployment detection uses both helpers, so a privacy-motivated helper change can also alter row context. - If a new caller tier should be allowed to call
$.telemetry, update mods/…/served-tiers.ts and verify the refusal text in mods/…/refused.ts;Gate.serveduses a plain string membership check againstnext.origin.tier, so no type-level exhaustiveness check will catch a missed tier. - If adding a deployment name, update all three sides together: mods/…/deployments.ts for priority, mods/…/register.ts or the Linux-file probe for the signal source, and any row-context expectations around
deploymentEnvironment.deploymentOfignores signals whose names are not present inDEPLOYMENTS, and when multiple signals hold the earlier deployment inDEPLOYMENTSwins regardless of signal order. - If gateway policy fields change, verify mods/…/is-analytics-off.ts against the
PolicyPinssource. The privacy decision treatsforceLoginMethod === 'gateway'and any definedforceLoginGatewayUrlas send blockers even when the runtimeCLAUDE_CODE_USE_GATEWAYvariable is absent.
Risks
- mods/…/is-analytics-off.ts disables telemetry on any non-empty custom OAuth URL after trimming, but
isEnvSetitself does not trim. If a future caller reusesisEnvSetdirectly for trimmed privacy switches, whitespace-only values may be treated inconsistently and either over-block or under-block sends. - mods/…/deployments.ts controls priority globally while mods/…/register.ts emits multiple signals for some platforms (
coder,devpod,aws-cloud9,railway,fly.io,azure-app-service). If a broad signal such asci,gcp, orkubernetesis moved earlier inDEPLOYMENTS, more specific deployments can be masked and rows will report the wrongdeploymentEnvironment.