Cost Analytics & Observability

Claude Code runs two entirely separate observability stacks in parallel. One is an internal first-party (1P) pipeline backed by OpenTelemetry and proto-serialised events shipped to /api/event_logging/batch. The other is a Datadog HTTP-intake fanout for operational monitoring. A thin sink layer sits in the middle and decides which pipeline receives each event — and whether to send it at all.

Every API response carries a BetaUsage object. addToTotalSessionCost() is the single entry-point that fans cost data out to three destinations simultaneously: in-memory accumulators, OpenTelemetry counters, and the analytics event log.

// 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
}

Cost is stored in microdollars when sent as analytics metadata (cost_usd_micros) to keep the value as an integer. The raw float is used for OTel counters. This prevents floating-point accumulation errors in event payloads.

Session Persistence

When the session ends (or is suspended) saveCurrentSessionCosts() writes the full snapshot to the project config JSON. On resume, restoreCostStateForSession() rehydrates the in-memory counters from that snapshot — but only when the sessionId in config matches the current session.

// 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 is deceptively small — 22 lines — but it wires cost saving into the React lifecycle so that the CLI's exit handler always captures accumulated cost state, regardless of how the process terminates.

// 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) }
  }, [])
}

The analytics module (services/analytics/index.ts) deliberately has zero dependencies to prevent import cycles. It exposes only three functions: logEvent, logEventAsync, and attachAnalyticsSink. Everything else — Datadog, 1P, GrowthBook — lives outside this file.

// 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)
}

The sink implementation (services/analytics/sink.ts) routes each event through the sampling gate, then fans out to Datadog (after stripping _PROTO_* keys) and the 1P pipeline (with the full payload).

// 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 receives a curated allowlist of ~40 events. Events not in DATADOG_ALLOWED_EVENTS are silently dropped. This allowlist exists to keep the Datadog index small and prevent accidental leakage of high-volume internal events.

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
})

The 1P pipeline is built on top of the OpenTelemetry Logs SDK. A dedicated LoggerProvider — distinct from the customer-facing telemetry provider — drives a BatchLogRecordProcessor that buffers events and exports them to Anthropic's internal endpoint in batches.

Resilience: Disk-Backed Retry

When a POST fails, failed events are appended to a per-session JSONL file at ~/.claude/telemetry/1p_failed_events.<sessionId>.<BATCH_UUID>.json. On the next startup, retryPreviousBatches() scans for any leftover files from the same session and retries them. This means events survive process crashes and temporary network outages.

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 Separation

The 1P LoggerProvider is never registered globally via logs.setGlobalLoggerProvider(). Customer-facing OTLP telemetry uses the global provider. Internal event logging uses a module-local provider, so customer OTLP endpoints never see internal Anthropic events and vice versa.

// 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 uses a TypeScript phantom-type system to enforce PII hygiene at compile time, and a runtime key-naming convention to route sensitive values only to privileged storage.

Compile-Time Guards: never-typed marker types

// 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

Runtime Guard: _PROTO_* Key Convention

Values that are PII but acceptable in privileged BigQuery columns (e.g. skill names, plugin names) are added to event payloads under keys prefixed with _PROTO_. The sink calls stripProtoFields() before Datadog fanout. The 1P exporter hoists known _PROTO_ keys to dedicated proto fields, then calls stripProtoFields() again as a defensive catch-all.

// 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 serves three distinct purposes in the analytics stack: feature flags for code behaviour, dynamic configuration for pipeline tuning, and experiment assignment tracking.

// 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

Live Pipeline Reinitialisation

Long-running sessions pick up batch config changes automatically. When GrowthBook refreshes, reinitialize1PEventLoggingIfConfigChanged() compares the new config against lastBatchConfig. If different, it nulls the logger (so concurrent emits see no logger and bail cleanly), force-flushes the old buffer to disk, swaps in a new provider, then shuts down the old one in the background.

Enterprises can opt in to receive telemetry at their own OTLP endpoint by setting CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_EXPORTER_OTLP_ENDPOINT. This path uses the global OTel providers and is entirely separate from the 1P analytics pipeline.

BigQuery Metrics Exporter

API customers, C4E (Claude for Enterprise), and Teams users additionally get a BigQueryMetricsExporter that posts to /api/claude_code/metrics every 5 minutes. This is separate from customer OTLP — it runs whether or not CLAUDE_CODE_ENABLE_TELEMETRY is set.

// 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
}

Analytics is disabled under four conditions, checked in 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 Event Dispatch

The 1P exporter probes auth state before every POST. If the OAuth token is expired, lacks the user:profile scope, or the trust dialog has not been accepted, it falls back to sending events without auth headers. A 401 response also triggers an automatic retry without auth. Events are never dropped solely because auth is unavailable — they degrade to unauthenticated delivery.