分析与遥测

01 架构概述

Claude Code 的分析系统分为六个文件 services/analytics/。 设计分开 what 登录自 how 事件被路由，保持公共 API 不依赖，以便任何模块都可以调用 logEvent() 无需在导入时引入 Datadog 或 OTel 传输。

02 预接收队列

由于分析导入发生在应用程序完全初始化之前，因此启动期间触发的事件将会丢失。 index.ts 使用模块级数组解决这个问题：

// index.ts — simplified
const eventQueue: QueuedEvent[] = []
let sink: AnalyticsSink | null = null

export function logEvent(eventName: string, metadata: LogEventMetadata): void {
  if (sink === null) {
    eventQueue.push({ eventName, metadata, async: false })
    return
  }
  sink.logEvent(eventName, metadata)
}

export function attachAnalyticsSink(newSink: AnalyticsSink): void {
  if (sink !== null) return  // idempotent
  sink = newSink

  if (eventQueue.length > 0) {
    const queuedEvents = [...eventQueue]
    eventQueue.length = 0
    queueMicrotask(() => {
      for (const event of queuedEvents) { sink!.logEvent(event.eventName, event.metadata) }
    })
  }
}

03 接收器路由——sink.ts

sink.ts 是交通警察。 对于每个事件，它在调度之前都会应用三个顺序检查：

// sink.ts — logEventImpl
function logEventImpl(eventName: string, metadata: LogEventMetadata): void {
  const sampleResult = shouldSampleEvent(eventName)
  if (sampleResult === 0) return  // dropped by sampling

  const metadataWithSampleRate =
    sampleResult !== null
      ? { ...metadata, sample_rate: sampleResult }
      : metadata

  if (shouldTrackDatadog()) {
    // strip _PROTO_* keys — PII tagged, Datadog is general-access
    void trackDatadogEvent(eventName, stripProtoFields(metadataWithSampleRate))
  }
  // 1P exporter receives the full payload including _PROTO_* keys
  logEventTo1P(eventName, metadataWithSampleRate)
}

04 数据狗传输

Datadog 收到一份精心策划的事件允许列表。 活动不在 DATADOG_ALLOWED_EVENTS 都被默默丢弃。 这使得 Datadog 专注于运营监控而不是产品分析。

// datadog.ts — batching + flush
const DEFAULT_FLUSH_INTERVAL_MS = 15000
const MAX_BATCH_SIZE = 100
const NETWORK_TIMEOUT_MS = 5000

function scheduleFlush(): void {
  if (flushTimer) return
  flushTimer = setTimeout(() => {
    flushTimer = null
    void flushLogs()
  }, getFlushIntervalMs()).unref()  // .unref() — never blocks process exit
}

// Flush immediately if batch is full, otherwise schedule
if (logBatch.length >= MAX_BATCH_SIZE) {
  void flushLogs()
} else {
  scheduleFlush()
}

基数减少

在构建 Datadog 标签之前，一些标准化可以减少度量基数：

05 元数据丰富——metadata.ts

每场活动都充满了丰富的内容 EventMetadata 组装的对象 getEventMetadata()。 这包括三个嵌套层：

EnvContext {
  platform: 'darwin' | 'linux' | 'windows'
  platformRaw:          // raw process.platform (freebsd visible here, not bucketed)
  arch: 'arm64' | 'x64'
  nodeVersion:          // runtime version string
  terminal:             // $TERM_PROGRAM
  packageManagers:      // comma-joined: 'npm,bun'
  runtimes:             // node, bun, deno detection
  isCi:                 // $CI env var
  isGithubAction:       // $GITHUB_ACTIONS
  isClaudeAiAuth:       // OAuth vs API key auth
  version:              // full semver build string
  wslVersion:           // WSL 1/2 if applicable
  vcs:                   // 'git' | 'hg' | ... detected VCS
  // + GitHub Actions runner metadata, container IDs, remote session IDs
}

ProcessMetrics {
  uptime:           // process.uptime()
  rss:              // resident set size in bytes
  heapTotal:        // V8 heap allocated
  heapUsed:         // V8 heap in use
  cpuPercent:       // delta since last event (user+sys µs / wall-clock ms)
  constrainedMemory: // process.constrainedMemory() if available
}

EventMetadata {
  agentId?:         // CLAUDE_CODE_AGENT_ID or subagent UUID
  parentSessionId?:  // lead session for cross-session joining in BQ
  agentType?:        // 'teammate' | 'subagent' | 'standalone'
  teamName?:         // swarm team label
  rh?:               // first 16 chars of SHA-256(repo remote URL)
  subscriptionType?: // 'max' | 'pro' | 'enterprise' | 'team'
  kairosActive?:     // ant-only KAIROS assistant flag
}

06 metadata.ts 中的 PII 清理

类型系统本身强制要求在记录之前检查字符串。 事件元数据中的任何字符串值都必须转换为两种标记类型之一 - 两者都键入为 never，因此它们只能用作记录开发人员意图的转换：

// You cannot store a value in these types — they're "never".
// They exist solely as cast targets to document a review decision.
export type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = never
export type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED = never

// Usage example — sanitizing MCP tool names:
export function sanitizeToolNameForAnalytics(toolName: string) {
  if (toolName.startsWith('mcp__')) {
    return 'mcp_tool' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
  }
  return toolName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
}

工具输入截断

When OTEL_LOG_TOOL_DETAILS=1 设置后，工具输入将针对 OTel 范围进行序列化。 超过 512 个字符的字符串将被截断为 128 个字符，并带有长度注释。 对象限制为深度 2 和 20 个项目。 总 JSON 的上限为 4 KB。

文件扩展名提取

对于 bash 工具调用，Claude Code 从已知命令中提取文件扩展名（cat, mv, cp, rm等）来跟踪正在操作的文件类型 - 而不记录实际的文件路径。 超过 10 个字符的扩展名将被编辑为 "other" 以防止基于哈希的文件名泄漏。

07 功能标志 — GrowthBook

GrowthBook 驱动器具有标志、A/B 实验、动态配置和终止开关。 Claude Code 使用其 远程评估 模式：服务器评估该用户的所有规则并返回预先计算的值，而不是将完整的规则树发送到客户端。

用于定位的用户属性

GrowthBookUserAttributes {
  id:               // stable device UUID
  sessionId:        // per-session ID
  deviceID:         // same as id
  platform:         // 'win32' | 'darwin' | 'linux'
  organizationUUID?: // enterprise org targeting
  accountUUID?:     // account-level targeting
  subscriptionType?: // 'max' | 'pro' | 'enterprise' | 'team'
  email?:           // ant-only: always included for internal targeting
  appVersion?:      // semver for version-range gates
  github?:          // GitHub Actions runner metadata
}

三级优先级

SDK 解决方法 — 远程评估格式

GrowthBook API 返回特征值 { "value": ... } 形状，但 SDK 期望 { "defaultValue": ... }。 Claude Code 通过在加载之前转换有效负载并维护其自己的负载来解决此问题 remoteEvalFeatureValues 绕过 SDK 本地重新评估的映射：

// growthbook.ts — processRemoteEvalPayload (simplified)
for (const [key, feature] of Object.entries(payload.features)) {
  if ('value' in feature && !('defaultValue' in feature)) {
    transformedFeatures[key] = { ...feature, defaultValue: feature.value }
  }
  // Cache evaluated value directly to avoid SDK re-evaluation
  remoteEvalFeatureValues.set(key, feature.value ?? feature.defaultValue)
}

实验曝光重复数据删除

当 GrowthBook 将用户分配给实验变体时，Claude Code 会记录一个 曝光事件 到 1P 后端进行正确的实验分析。 模块级 loggedExposures 设置确保每个功能在每个会话中最多触发一次曝光事件 - 防止调用的热代码路径中出现重复条目 getFeatureValue 在每个渲染上。

08 终止开关

如果分析中的错误导致出现问题（流量过大、意外 PII 等），Anthropic 可以远程禁用各个接收器，而无需发布新版本：

// sinkKillswitch.ts
// Deliberately obfuscated config key to avoid easy discovery
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'

export function isSinkKilled(sink: 'datadog' | 'firstParty'): boolean {
  const config = getDynamicConfig_CACHED_MAY_BE_STALE<
    Partial<Record<'datadog' | 'firstParty', boolean>>
  >('tengu_frond_boric', {})
  return config?.[sink] === true
}

09 当分析被禁用时

config.ts 定义了完全抑制分析的条件：

export function isAnalyticsDisabled(): boolean {
  return (
    process.env.NODE_ENV === 'test'               // test environments
    || isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)  // AWS Bedrock
    || isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)   // GCP Vertex
    || isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)  // Azure Foundry
    || isTelemetryDisabled()                          // user privacy setting
  )
}

第三方云提供商（Bedrock、Vertex、Foundry）完全禁用分析 - 如果没有 Anthropic 身份验证上下文，事件数据将毫无意义，并且这些用户拥有自己的日志记录管道。 这 isTelemetryDisabled() 路径尊重用户的隐私级别设置。

10 事件采样

高频事件（例如 tengu_api_success 在繁忙的会话中）可以产生巨大的音量。 GrowthBook配置键 tengu_event_sampling_config 让 Anthropic 设置每个事件的采样率，无需更改代码：

// firstPartyEventLogger.ts — shouldSampleEvent
export function shouldSampleEvent(eventName: string): number | null {
  const config = getEventSamplingConfig()   // from GrowthBook cache
  const eventConfig = config[eventName]

  if (!eventConfig) return null             // no config = 100% logging

  const sampleRate = eventConfig.sample_rate
  if (sampleRate <= 0)  return 0            // 0 = drop everything
  if (sampleRate >= 1)  return null         // 1 = keep everything (no annotation needed)

  // Probabilistic: roll the dice
  return Math.random() < sampleRate
    ? sampleRate    // sampled — return rate so it can be added to event metadata
    : 0            // not sampled — sink drops it
}

当对事件进行采样时， sample_rate 附加到其元数据中。 这使得分析师可以应用逆概率加权来重建未采样的总数。

11 文件参考

12 要点