Claude Code Observability: Dual-Sink Analytics, OTEL Spans, Perfetto Traces

Observability in a local-first agent runtime is harder than in a server: there is no always-on backend to receive events, sessions may be offline, and PII is on the user's machine.

Claude Code has a layered solution: dual-sink analytics, OpenTelemetry spans, BigQuery output, and Perfetto traces for deep performance analysis.

File structure

src/
├── services/
│   ├── analytics/
│   │   ├── index.ts
│   │   ├── types.ts
│   │   └── bucketHash.ts
└── utils/
    └── telemetry/
        ├── otel.ts
        ├── betaSessionTracing.ts
        └── perfetto.ts

The dual-sink design

The PII enforcement design

The type name AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS is one of the most deliberate design choices in the codebase.

It is a never-type marker — a TypeScript type that cannot be assigned any value except never, meaning the only way to use it is to explicitly cast and declare the verification.

The consequence: passing a file path or code snippet as analytics event metadata is a compile-time error, not a runtime check.

This matters because analytics metadata ends up in Datadog dashboards and BigQuery tables that may be accessible to many people. If code or file paths accidentally end up there, they could expose source code, credentials in file names, or personal paths.

The verification type forces every call site to explicitly attest that its metadata is safe.

Why OTEL spans wrap more than the model call

A common pattern in agent instrumentation is to put a span only around the model API call — measure latency, record token counts, done.

Claude Code wraps a much wider surface: the full turn, including tool execution, permission checks, MCP client calls, and task spawning.

This matters because in a real agent session, the model call is often not the slowest part. A tool that runs a shell command, a permission prompt waiting for user input, an MCP server that times out — these all appear in the span tree, giving a complete picture of where a slow turn actually spent its time.

Perfetto and Chrome Trace format

The telemetry layer also supports Perfetto trace export in Chrome Trace format.

Perfetto is Google's system profiler. The Chrome Trace format is readable in chrome://tracing, Perfetto UI, and Speedscope.

This is not for production monitoring — it is for deep performance analysis of individual sessions. A developer investigating a slow turn can export a Perfetto trace and see exactly how the span tree corresponds to CPU and wall-clock time.

// PII enforcement: this type can only be assigned by explicit verification
// The verbose name is the enforcement — it is not an accident
declare const _VERIFIED: unique symbol
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = {
readonly [_VERIFIED]: true
[key: string]: string | number | boolean
}

function verifyMetadata(
m: Record<string, string | number | boolean>
): AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS {
// Call site must explicitly invoke this — the type name is the documentation
return m as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
}

interface AnalyticsEvent {
name: string
metadata: AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
userId?: string
}

// Dual sink: both sinks always receive the same event
async function trackEvent(event: AnalyticsEvent): Promise<void> {
await Promise.allSettled([
  datadogSink.emit(event),
  firstPartySink.emit(event)
])
}

// User bucket hashing for stable A/B assignment
function getUserBucket(userId: string, bucketCount = 100): number {
const hash = murmurhash(userId)
return hash % bucketCount
}

// OTEL span wrapping the full turn — not just the model call
async function runTurnWithSpan(
input: string,
context: SessionContext
): Promise<TurnResult> {
return tracer.startActiveSpan('turn.execute', async (span) => {
  span.setAttributes({
    'turn.input_length': input.length,
    'session.id': context.sessionId,
  })

  try {
    const result = await runTurn(input, context)
    span.setStatus({ code: SpanStatusCode.OK })
    span.setAttributes({ 'turn.tool_calls': result.toolCallCount })
    return result
  } catch (err) {
    span.setStatus({ code: SpanStatusCode.ERROR })
    span.recordException(err as Error)
    throw
  } finally {
    span.end()
  }
})
}