Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / telemetry-event-pipeline-and-sending

Telemetry event pipeline and sending

Overview

The telemetry pipeline turns $.telemetry.log and $.telemetry.mark calls into first-party event-logging POSTs. Its public hook answer boundary is mods/…/answer-of.ts: queueing success resolves as { value: undefined }, while validation failures created by mods/…/refusal.ts are converted to { deny: <reason> }; other errors are rethrown so the engine treats them as hook failures.

Entry validation and row shaping live under mods/telemetry/hooks/entries/**. mods/…/checked-fields.ts accepts one log entry object, requires event to match TOKEN (/^[a-z][a-z0-9_]{0,63}$/ in mods/…/token.ts), defaults missing props to {}, and refuses malformed entries before anything is queued. mods/…/fields-of.ts prefixes ordinary events with tengu_plugin_ from mods/…/event-prefix.ts, but keeps names that already start with tengu_ from mods/…/core-event-prefix.ts.

Property checking is deliberately restrictive. mods/…/checked-props.ts accepts only plain-object props, caps them at PROP_LIMIT = 16 from mods/…/prop-limit.ts, and requires every key to be a TOKEN. mods/…/checked-value.ts allows booleans, finite numbers, or Choice objects; bare strings are refused as free text. Choice lists must contain 1-32 members (mods/…/choices-limit.ts), every member must match CHOICE_TOKEN from mods/…/choice-token.ts, and the chosen value must be one of those members. Tests in mods/…/register.test.ts assert that free text, non-finite numbers, bad keys, malformed events, and Choice values outside of produce hook denials and no HTTP posts.

Marks use the same prop validation but produce product feature rows instead of plugin-prefixed rows. mods/…/checked-mark.ts requires { feature, kind, reason?, props? }, validates feature and non-OK reason as TOKENs, and limits kind to ok, sad, or bad via mods/…/mark-kinds.ts and mods/…/is-mark-kind.ts. mods/…/mark-fields-of.ts emits tengu_feature_<kind> using mods/…/feature-prefix.ts; OK marks carry feature_name plus props, while sad/bad marks carry props, feature_name, and error_code. mods/…/register.test.ts covers successful feature rows and refusals for bad kinds, missing/extra reasons, and bad feature names.

Batch payload construction starts from queued PendingRows (mods/…/pending-row.ts), each of which stores checked fields plus a generated event id and log timestamp. mods/…/batch-of.ts serializes { events: [...] }, one ClaudeCodeInternalEvent per row. Each event data object is assembled by mods/…/event-data-of.ts: row id/name/timestamp, batch-time session values (sessionId, model, userType, isInteractive, isClaudeAiAuth), identity fields (deviceId, email, optional auth from mods/…/auth-of.ts), session/context fields, env, and additionalMetadata. mods/…/metadata-of.ts base64-encodes JSON containing { rh: <remoteHash>, ...props }. Finally, mods/…/wire-of.ts recursively converts camelCase object keys to snake_case for the ingest while preserving arrays and scalar values.

Batch timing and retry constants live in mods/telemetry/hooks/batching/**: BATCH_WINDOW_MS = 5000 (mods/…/batch-window-ms.ts), BATCH_ROWS = 100 (mods/…/batch-rows.ts), RETRY_DELAY_MS = 500 (mods/…/retry-delay-ms.ts), and retriable statuses are 5xx, 408, and 429 (mods/…/is-retriable.ts plus status constants). The sender shape itself is only typed in mods/…/sender.ts: telemetry is the noun and flush() sends queued rows. The actual orchestrator in mods/…/telemetry-of.ts queues rows, starts the 5-second timer, flushes immediately when 100 rows accumulate, and serializes sends by chaining onto an internal sending promise. It reads analytics switches before each batch, authorizes a first-party credential, stamps batch values, POSTs to INGEST_URL (https://api.anthropic.com/api/event_logging/v2/batch in mods/…/ingest-url.ts), retries once after RETRY_DELAY_MS when the first POST throws or returns a retriable status, and writes debug lines for sent or dropped batches.

The config-location shape owned here is mods/…/config-location.ts: configDir, home, and userProfile identify where the CLI global config can be read from; the comments are explicit that this location is used to find the file and is never sent. Tests define the expected paths and resulting identity fields through mods/…/config-path.ts, mods/…/global-config.ts, and mods/…/first-party-session.ts. mods/…/register.test.ts asserts that config, machine, and environment facts are cached/read once per session and that Windows uses USERPROFILE while the basic sending fixture uses HOME.

The tests and fixtures under mods/telemetry/tests/** are the executable specification for the wire format. mods/…/batch-of.ts parses http.fetch bodies, mods/…/rows-of.ts flattens all posted events, verifies event ids and timestamps are present, and decodes additional_metadata through mods/…/base64-decoded.ts. mods/…/expected-row.ts captures the canonical row for a survey answer: event_type: ClaudeCodeInternalEvent, event_name: tengu_plugin_survey_answered, device/email/auth/session/model/user type/interactive fields, a populated env block, and decoded metadata { rh, answer, page, seen }. mods/…/register.test.ts covers timer batching, full-queue flushing, session-end flushing, analytics-off gates, missing credentials, retry behavior, and environment variants; mods/…/gate.test.ts verifies that higher hooks cannot rename, swallow, replace, or redirect rows emitted by the collector stream.

Coverage / routing

This document owns:

  • mods/telemetry/hooks/answer-of/**
  • mods/telemetry/hooks/entries/**
  • mods/telemetry/hooks/batching/**
  • mods/telemetry/hooks/sender/**
  • mods/telemetry/hooks/config-location/**
  • mods/telemetry/tests/**

Use this doc for changes to telemetry entry validation, mark/log row shaping, batching constants and retry rules, sender transport semantics, config-location fields used to find the global config, or tests/fixtures that define the posted ingest payload.

Coupling

Risks

  • mods/…/wire-of.ts rewrites every uppercase letter in every object key recursively. If a metadata prop or environment object intentionally needs an uppercase key, it will be sent lower-snake-cased without an error; the consequence is a wire-format mismatch that only shows up if mods/…/rows-of.ts or specific row assertions check the final key.
  • mods/…/metadata-of.ts uses btoa(JSON.stringify(...)) for additionalMetadata. If future checked props ever allow non-ASCII text, base64 encoding can break in runtimes where btoa only accepts binary strings; the current validators in mods/…/checked-value.ts avoid this by refusing free text and only allowing token Choice strings.
  • mods/…/checked-props.ts and mods/…/checked-value.ts reject at the first invalid property. Reordering object construction in callers or changing iteration behavior would change which denial text reaches answerOf, which can break the exact refusal assertions in mods/…/register.test.ts.