成本分析

Claude Code 运行 两个完全独立的可观察性堆栈 并联。 一个是内部第一方 (1P) 管道，由 OpenTelemetry 和发送到的原始序列化事件支持 /api/event_logging/batch。 另一个是用于运行监控的 Datadog HTTP 接收扇出。 一个薄薄的 sink 层位于中间，决定哪个管道接收每个事件 - 以及是否发送它。

每个 API 响应都带有一个 BetaUsage object. addToTotalSessionCost() 是风扇将数据同时发送到三个目的地的单一入口点：内存中累加器、OpenTelemetry 计数器和分析事件日志。

// cost-tracker.ts
export function addToTotalSessionCost(
  cost: number,
  usage: Usage,
  model: string,
): number {
  // 1. Accumulate per-model token counters in memory
  const modelUsage = addToTotalModelUsage(cost, usage, model)
  addToTotalCostState(cost, modelUsage, model)

  // 2. Push to OTel counters (for BigQuery / customer OTLP)
  const attrs = isFastModeEnabled() && usage.speed === 'fast'
    ? { model, speed: 'fast' }
    : { model }

  getCostCounter()?.add(cost, attrs)
  getTokenCounter()?.add(usage.input_tokens,  { ...attrs, type: 'input' })
  getTokenCounter()?.add(usage.output_tokens, { ...attrs, type: 'output' })
  getTokenCounter()?.add(usage.cache_read_input_tokens ?? 0,
    { ...attrs, type: 'cacheRead' })
  getTokenCounter()?.add(usage.cache_creation_input_tokens ?? 0,
    { ...attrs, type: 'cacheCreation' })

  // 3. Log advisor sub-usage to 1P analytics
  let totalCost = cost
  for (const advisorUsage of getAdvisorUsage(usage)) {
    const advisorCost = calculateUSDCost(advisorUsage.model, advisorUsage)
    logEvent('tengu_advisor_tool_token_usage', {
      advisor_model: advisorUsage.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
      input_tokens: advisorUsage.input_tokens,
      cost_usd_micros: Math.round(advisorCost * 1_000_000),
    })
    totalCost += addToTotalSessionCost(advisorCost, advisorUsage, advisorUsage.model)
  }
  return totalCost
}

成本存储在 microdollars 当作为分析元数据发送时（cost_usd_micros) 将值保留为整数。 原始浮点数用于 OTel 计数器。 这可以防止事件负载中出现浮点累积错误。

会话保持

当会话结束（或暂停）时 saveCurrentSessionCosts() 将完整快照写入项目配置 JSON。 简历上， restoreCostStateForSession() 从该快照中重新水化内存中的计数器 - 但仅当 sessionId 在配置中匹配当前会话。

// Save on process exit via useCostSummary React hook
export function saveCurrentSessionCosts(fpsMetrics?: FpsMetrics): void {
  saveCurrentProjectConfig(current => ({
    ...current,
    lastCost:                          getTotalCostUSD(),
    lastAPIDuration:                   getTotalAPIDuration(),
    lastAPIDurationWithoutRetries:     getTotalAPIDurationWithoutRetries(),
    lastTotalInputTokens:              getTotalInputTokens(),
    lastTotalOutputTokens:             getTotalOutputTokens(),
    lastTotalCacheCreationInputTokens: getTotalCacheCreationInputTokens(),
    lastTotalCacheReadInputTokens:     getTotalCacheReadInputTokens(),
    lastTotalWebSearchRequests:        getTotalWebSearchRequests(),
    lastFpsAverage:                    fpsMetrics?.averageFps,
    lastModelUsage:                    Object.fromEntries(
      Object.entries(getModelUsage()).map(([model, u]) => [
        model,
        { inputTokens: u.inputTokens, outputTokens: u.outputTokens,
          cacheReadInputTokens: u.cacheReadInputTokens,
          cacheCreationInputTokens: u.cacheCreationInputTokens,
          costUSD: u.costUSD },
      ])
    ),
    lastSessionId: getSessionId(),
  }))
}

// Restore only when session IDs match
export function restoreCostStateForSession(sessionId: string): boolean {
  const data = getStoredSessionCosts(sessionId)
  if (!data) return false
  setCostStateForRestore(data)
  return true
}

costHook.ts 看似很小（22 行），但它将成本节省连接到 React 生命周期中，以便 CLI 的退出处理程序始终捕获累积的成本状态，无论进程如何终止。

// costHook.ts — full file
import { useEffect } from 'react'
import { formatTotalCost, saveCurrentSessionCosts } from './cost-tracker.js'
import { hasConsoleBillingAccess } from './utils/billing.js'
import type { FpsMetrics } from './utils/fpsTracker.js'

export function useCostSummary(
  getFpsMetrics?: () => FpsMetrics | undefined,
): void {
  useEffect(() => {
    const f = () => {
      // Only print the summary if the user has console billing access
      if (hasConsoleBillingAccess()) {
        process.stdout.write('\n' + formatTotalCost() + '\n')
      }
      saveCurrentSessionCosts(getFpsMetrics?.())
    }
    process.on('exit', f)
    return () => { process.off('exit', f) }
  }, [])
}

分析模块（services/analytics/index.ts）故意有 零依赖 以防止导入循环。 它仅公开三个功能： logEvent, logEventAsync， 和 attachAnalyticsSink。 其他所有内容——Datadog、1P、GrowthBook——都位于该文件之外。

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

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) {
        event.async
          ? void sink!.logEventAsync(event.eventName, event.metadata)
          :       sink!.logEvent(event.eventName, event.metadata)
      }
    })
  }
}

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

接收器实现（services/analytics/sink.ts）通过采样门路由每个事件，然后扇出到 Datadog（剥离后 _PROTO_* 键）和 1P 管道（具有完整的有效负载）。

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

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

  if (shouldTrackDatadog()) {
    // Strip _PROTO_* keys — Datadog is general-access, PII must stay out
    void trackDatadogEvent(eventName, stripProtoFields(metadataWithSampleRate))
  }
  // 1P receives full payload; exporter handles PII routing internally
  logEventTo1P(eventName, metadataWithSampleRate)
}

Datadog 收到一份包含约 40 个事件的精选许可名单。 活动不在 DATADOG_ALLOWED_EVENTS 都被默默地丢弃了。 此白名单的存在是为了保持 Datadog 索引较小并防止大量内部事件的意外泄漏。

const NUM_USER_BUCKETS = 30

const getUserBucket = memoize((): number => {
  const userId = getOrCreateUserID()
  const hash = createHash('sha256').update(userId).digest('hex')
  return parseInt(hash.slice(0, 8), 16) % NUM_USER_BUCKETS
})

1P管道建立在 OpenTelemetry 日志 SDK。 一个专门的 LoggerProvider - 与面向客户的遥测提供商不同 - 推动 BatchLogRecordProcessor 缓冲事件并将它们批量导出到 Anthropic 的内部端点。

弹性：磁盘支持的重试

当 POST 失败时，失败的事件将附加到每个会话的 JSONL 文件中，位置为 ~/.claude/telemetry/1p_failed_events.<sessionId>.<BATCH_UUID>.json。 下次启动时， retryPreviousBatches() 扫描同一会话中的任何剩余文件并重试。 这意味着事件可以在进程崩溃和临时网络中断的情况下幸存下来。

private scheduleBackoffRetry(): void {
  if (this.cancelBackoff || this.isRetrying || this.isShutdown) return

  // Quadratic backoff: base * attempts²  (matches Statsig SDK)
  const delay = Math.min(
    this.baseBackoffDelayMs * this.attempts * this.attempts,
    this.maxBackoffDelayMs,  // caps at 30 000 ms
  )

  this.cancelBackoff = this.schedule(async () => {
    this.cancelBackoff = null
    await this.retryFailedEvents()
  }, delay)
}

OTel LoggerProvider 分离

1P LoggerProvider is 从未在全球注册过 via logs.setGlobalLoggerProvider()。 面向客户的 OTLP 遥测使用全球提供商。 内部事件日志记录使用模块本地提供程序，因此客户 OTLP 端点永远不会看到内部 Anthropic 事件，反之亦然。

// firstPartyEventLogger.ts — two providers, never mixed
// The 1P provider is kept module-local:
let firstPartyEventLoggerProvider: LoggerProvider | null = null
let firstPartyEventLogger: Logger | null = null

// Customer telemetry uses the global provider in instrumentation.ts:
// logs.setGlobalLoggerProvider(loggerProvider)  ← customer endpoint
// setEventLogger(logs.getLogger(...))           ← customer event logger
//
// 1P provider is obtained from the local instance, NOT from logs.getLogger():
firstPartyEventLogger = firstPartyEventLoggerProvider.getLogger(
  'com.anthropic.claude_code.events',
  MACRO.VERSION,
)

Claude Code 使用 TypeScript 幻像类型系统在编译时强制实施 PII 卫生，并使用运行时键命名约定将敏感值仅路由到特权存储。

编译时防护：从不键入的标记类型

// services/analytics/index.ts

// Type is `never` — cannot hold a value, only used for casting.
// Any string passed to logEvent() must be explicitly cast to this type,
// forcing developers to verify it contains no code/file paths.
export type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = never

// Second marker for PII-tagged values destined for privileged BQ columns.
// These values travel with the event but are stripped before Datadog.
export type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED = never

运行时防护：_PROTO_* 键约定

属于 PII 但在特权 BigQuery 列中可接受的值（例如技能名称、插件名称）将添加到前缀为键下的事件负载中 _PROTO_。 水槽呼叫 stripProtoFields() 在Datadog扇出之前。 已知的 1P 出口商葫芦 _PROTO_ 键到专用原型字段，然后调用 stripProtoFields() 再次作为防守包罗万象。

// services/analytics/index.ts
export function stripProtoFields<V>(
  metadata: Record<string, V>,
): Record<string, V> {
  let result: Record<string, V> | undefined
  for (const key in metadata) {
    if (key.startsWith('_PROTO_')) {
      if (result === undefined) result = { ...metadata }
      delete result[key]
    }
  }
  return result ?? metadata  // same reference when no _PROTO_ keys present
}

// In the 1P exporter — hoist then strip:
const { _PROTO_skill_name, _PROTO_plugin_name, _PROTO_marketplace_name, ...rest } = formatted.additional
const additionalMetadata = stripProtoFields(rest)  // catches future unknown _PROTO_* keys

events.push({
  event_type: 'ClaudeCodeInternalEvent',
  event_data: ClaudeCodeInternalEvent.toJSON({
    skill_name: typeof _PROTO_skill_name === 'string' ? _PROTO_skill_name : undefined,
    additional_metadata: Buffer.from(jsonStringify(additionalMetadata)).toString('base64'),
  }),
})

GrowthBook 在分析堆栈中具有三个不同的用途：代码行为的功能标志、管道调整的动态配置以及实验分配跟踪。

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

  if (!eventConfig) return null            // not configured → log 100%

  const sampleRate = eventConfig.sample_rate
  if (typeof sampleRate !== 'number' || sampleRate < 0 || sampleRate > 1)
    return null                              // invalid → fail-open (log 100%)
  if (sampleRate >= 1) return null           // rate=1 → log 100%, no metadata overhead
  if (sampleRate <= 0) return 0             // rate=0 → drop

  return Math.random() < sampleRate ? sampleRate : 0
}

// Caller in sink.ts:
// null   → event passes through, no sample_rate metadata added
// 0      → event dropped
// 0–1   → event passes, sample_rate added to metadata for downstream correction

实时管道重新初始化

长时间运行的会话会自动获取批量配置更改。 当GrowthBook刷新时， reinitialize1PEventLoggingIfConfigChanged() 将新配置与 lastBatchConfig。 如果不同，它将清空记录器（因此并发发出看不到记录器并干净地保释），将旧缓冲区强制刷新到磁盘，交换新的提供程序，然后在后台关闭旧的提供程序。

企业可以通过设置选择在自己的 OTLP 端点接收遥测数据 CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_EXPORTER_OTLP_ENDPOINT。 该路径使用 global OTel 提供商，完全独立于 1P 分析管道。

BigQuery 指标导出器

API 客户、C4E（Claude for Enterprise）和 Teams 用户还可以获得 BigQueryMetricsExporter 发布到 /api/claude_code/metrics 每 5 分钟一次。 这与客户 OTLP 是分开的 — 无论是否运行，它都会运行 CLAUDE_CODE_ENABLE_TELEMETRY 已设置。

// utils/telemetryAttributes.ts
const METRICS_CARDINALITY_DEFAULTS = {
  OTEL_METRICS_INCLUDE_SESSION_ID:   true,   // included by default
  OTEL_METRICS_INCLUDE_VERSION:      false,  // excluded by default
  OTEL_METRICS_INCLUDE_ACCOUNT_UUID: true,   // included by default
}

export function getTelemetryAttributes(): Attributes {
  const attributes: Attributes = { 'user.id': getOrCreateUserID() }

  if (shouldIncludeAttribute('OTEL_METRICS_INCLUDE_SESSION_ID'))
    attributes['session.id'] = getSessionId()

  if (shouldIncludeAttribute('OTEL_METRICS_INCLUDE_VERSION'))
    attributes['app.version'] = MACRO.VERSION

  // OAuth account data only when actively using OAuth
  const oauthAccount = getOauthAccountInfo()
  if (oauthAccount) {
    if (oauthAccount.organizationUuid) attributes['organization.id'] = oauthAccount.organizationUuid
    if (oauthAccount.email)            attributes['user.email']    = oauthAccount.email
  }
  return attributes
}

分析在四种情况下被禁用，已签入 isAnalyticsDisabled():

// services/analytics/config.ts
export function isAnalyticsDisabled(): boolean {
  return (
    process.env.NODE_ENV === 'test'                           ||
    isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)           ||  // AWS Bedrock
    isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)            ||  // Google Vertex
    isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)           ||  // Azure Foundry
    isTelemetryDisabled()                                          // privacy setting
  )
}

Auth-Aware 事件调度

1P 导出器在每次 POST 之前探测身份验证状态。 如果 OAuth 令牌已过期，则缺少 user:profile 范围，或者信任对话框尚未被接受，它会回退到发送没有身份验证标头的事件。 401 响应还会触发无需身份验证的自动重试。 事件永远不会仅仅因为身份验证不可用而被丢弃——它们会降级为未经身份验证的传递。