Modulo 5.5 Analytics & Telemetry - Claude Code Deep Dive

1

🏗️ Architecture Overview

O design separa o que e logado de como eventos roteiam. A API publica e zero-dep para que qualquer modulo possa chamar logEvent() sem importar transports.

index.ts

API publica + fila pre-sink

sink.ts

Router: sampling, kill-switch, PII strip, dispatch

datadog.ts

Batch logs, flush a cada 15s ou 100 entradas

metadata.ts

Platform, model, session, agent ID, metricas

growthbook.ts

Feature flags, A/B experiments, kill-switches

sinkKillswitch.ts

Emergency off-switch via config GrowthBook

2

📨 Pre-Sink Queue & Routing

Eventos disparados durante startup sao enfileirados em array module-level ate um sink anexar. A fila e drenada via queueMicrotask para evitar latencia no hot path de startup.

Sink Routing Pipeline

logEvent -> shouldSampleEvent? -> isSinkKilled(datadog)? -> shouldTrackDatadog? -> stripProtoFields -> trackDatadogEvent -> logEventTo1P (full payload)

PII Separation

Keys prefixadas _PROTO_ roteiam para colunas BigQuery privilegiadas. stripProtoFields() e chamado antes do fanout para Datadog.

3

📏 Metadata Enrichment

Cada evento e enriquecido com tres camadas aninhadas:

EnvContext -- platform, arch, nodeVersion, terminal, packageManagers, CI/GitHub Actions, VCS, version

ProcessMetrics -- uptime, rss, heapTotal, heapUsed, cpuPercent (delta desde ultimo evento)

Agent ID -- agentId, parentSessionId, agentType (teammate/subagent/standalone), teamName, repo hash

Atribuicao e automatica via AsyncLocalStorage (subagentes) ou env vars (teammates em processos separados).

4

🚩 GrowthBook Feature Flags

GrowthBook usa remote eval: o servidor avalia todas as regras e retorna valores pre-computados. Tres niveis de override:

Env Var -- CLAUDE_INTERNAL_FC_OVERRIDES (ant-only, para harnesses de eval)
Config -- Via /config Gates tab (ant-only, armazenado em ~/.claude.json)
Remote Eval -- Fetched de api.anthropic.com, cacheado em disco

Safety guard: Se o servidor retorna features vazio, processRemoteEvalPayload retorna false sem limpar o cache em disco, prevenindo blackout total de flags.

5

🛑 The Kill-Switch

Se um bug em analytics causa problemas, Anthropic pode desabilitar sinks individuais remotamente sem ship de release:

// Config key deliberadamente ofuscada
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'

function isSinkKilled(sink: 'datadog' | 'firstParty'): boolean {
  const config = getDynamicConfig('tengu_frond_boric', {})
  return config?.[sink] === true
}

Fail-open: Se config faltando ou GrowthBook nao carregou, isSinkKilled retorna false -- sinks ficam habilitados.

6

🚫 When Analytics is Disabled

Analytics e inteiramente suprimido quando:

NODE_ENV === 'test'
AWS Bedrock (CLAUDE_CODE_USE_BEDROCK)
GCP Vertex (CLAUDE_CODE_USE_VERTEX)
Azure Foundry (CLAUDE_CODE_USE_FOUNDRY)
Setting de privacidade do usuario (isTelemetryDisabled())

7

🎲 Event Sampling

Eventos de alta frequencia podem gerar volume enorme. GrowthBook config tengu_event_sampling_config permite taxas de amostragem por evento sem mudanca de codigo.

Quando um evento e amostrado, o sample_rate e adicionado aos metadados para que analistas apliquem ponderacao de probabilidade inversa para reconstruir totais.

📋 Resumo do Modulo

✅API publica zero-dep -- qualquer modulo pode chamar logEvent() sem criar ciclos de import

✅Sanitizacao type-enforced -- strings requerem cast explicito para marker type. Nenhuma string alcanca backend sem sign-off

✅GrowthBook como control plane -- sampling, feature gates, A/B, kill-switches por um unico endpoint remote-eval

✅Fail-open em toda parte -- configs faltantes, fetches falhos, outages GrowthBook sempre default para analytics rodando

✅Swarm-aware -- agent type, team name, parent session ID automaticamente anexados via AsyncLocalStorage