분석 & 텔레메트리

Claude Code의 분석 시스템은 제로 의존성 원칙을 따르는 경량 텔레메트리 아키텍처입니다. 외부 분석 SDK 없이 자체 구현된 이벤트 수집, 배치 전송, 메타데이터 강화, PII 위생 처리를 제공합니다. 6개 파일로 구성된 모듈러 아키텍처가 이벤트의 전체 수명 주기를 관리합니다.

6파일 아키텍처의 책임 분리:

• index.ts: 공개 API — logEvent(), attachAnalyticsSink() 등 진입점 함수와 프리싱크 큐
• sink.ts: 싱크 라우터 — _PROTO_ 접두사 키에 따라 1P 전용 BigQuery 컬럼으로 라우팅하고 Datadog에 병렬 디스패치
• datadog.ts: Datadog 전송 — 약 40개 허용 이벤트 큐레이션, 배치 플러시, 카디널리티 감소
• metadata.ts: 메타데이터 강화 — EnvContext, ProcessMetrics, 에이전트 식별
• growthbook.ts: GrowthBook 기능 플래그 — 원격 평가, 3레벨 오버라이드, 노출 중복 제거
• sinkKillswitch.ts: 킬스위치 — tengu_frond_boric 키로 Datadog과 firstParty 싱크를 독립적으로 비활성화

logEvent()가 싱크 연결 전에 호출되면 이벤트가 인메모리 eventQueue에 푸시됩니다. attachAnalyticsSink()로 싱크가 연결되면 queueMicrotask로 대기열을 드레인합니다 — 시작 절차에 동기적 지연을 추가하지 않습니다. attachAnalyticsSink()는 멱등성 가드가 있어 중복 호출 시 두 번째 싱크를 무시합니다.

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  // 멱등
  sink = newSink
  if (eventQueue.length > 0) {
    const queued = [...eventQueue]
    eventQueue.length = 0
    queueMicrotask(() => {
      for (const e of queued) sink!.logEvent(e.eventName, e.metadata)
    })
  }
}

이벤트 메타데이터에서 _PROTO_ 접두사가 붙은 키는 1P(First-Party) 전용 BigQuery 컬럼으로 라우팅됩니다. Datadog으로 전송하기 전에 stripProtoFields()가 이러한 필드를 제거하여 내부 데이터가 외부 서비스로 유출되지 않도록 합니다.

라우팅 흐름

1. 이벤트 수신 시 _PROTO_ 필드 분리
2. shouldSampleEvent() 체크 — 샘플링 비율에 따라 이벤트 드롭 또는 통과
3. 통과한 이벤트를 1P 싱크와 Datadog에 병렬 디스패치
4. Datadog 전송 전 stripProtoFields()로 내부 전용 필드 제거

Datadog으로의 이벤트 전송은 효율성, 비용 최적화, 프라이버시를 동시에 고려합니다.

이벤트 큐레이션

약 40개의 허용된 이벤트만 Datadog으로 전송됩니다. 허용 목록에 없는 이벤트는 자동으로 드롭되어 불필요한 비용을 방지합니다.

배치 플러시

이벤트는 15초 간격 또는 100개 누적 시 (먼저 도달하는 조건) 배치로 전송됩니다. 개별 HTTP 요청의 오버헤드를 줄이고 네트워크 효율성을 높입니다.

카디널리티 감소

높은 카디널리티 태그(모델 이름, MCP 도구 이름 등)는 Datadog 비용을 급증시킵니다. 분석 시스템은 이러한 값을 정규화하여 카디널리티를 제한합니다:

• 모델 이름 정규화: 세부 버전 정보를 제거하고 기본 모델 패밀리로 그룹화
• MCP 도구 이름 정규화: 동적 도구 이름을 일반화

프라이버시 보존 카디널리티 추정

사용자 ID는 SHA-256으로 해싱된 후 30개 버킷으로 매핑됩니다. 이 방식은 개별 사용자를 식별할 수 없으면서도 고유 사용자 수를 약 3.3% 오차로 추정할 수 있게 합니다.

// datadog.ts — 30버킷 프라이버시 보존 해싱
function hashToBucket(userId: string): number {
  const hash = sha256(userId)
  return parseInt(hash.slice(0, 8), 16) % 30  // ~3.3% 오차
}

모든 이벤트는 전송 전에 세 가지 범주의 메타데이터로 강화됩니다.

EnvContext (환경 컨텍스트)

플랫폼, 아키텍처, 런타임 버전, CI 여부 등 환경 정보를 수집합니다. 이 정보는 세션 시작 시 한 번만 수집하고 메모이즈합니다 — 매 이벤트마다 재수집하면 불필요한 오버헤드가 발생합니다.

• OS 종류 및 버전 (macOS, Linux, Windows)
• Node.js 버전, Claude Code 버전
• 터미널 종류 (iTerm2, Terminal.app, VS Code 등)
• CI 환경 감지 (GitHub Actions, Jenkins 등)

ProcessMetrics (프로세스 메트릭)

RSS(Resident Set Size), 힙 사용량, CPU 퍼센트를 수집합니다. EnvContext와 달리 ProcessMetrics는 이벤트별 델타로 기록됩니다 — 시간에 따른 리소스 사용량 변화를 추적합니다.

에이전트 식별

이벤트 발생 컨텍스트에 따라 에이전트를 식별합니다:

• 서브에이전트: AsyncLocalStorage를 사용하여 메인 에이전트와 서브에이전트를 구분
• 스웜 팀메이트: 환경 변수로 스웜 내 팀메이트 식별

개인 식별 정보(PII)와 코드/파일 경로의 분석 백엔드 유출을 방지하기 위해 컴파일 타임과 런타임 양쪽에서 보호합니다.

never 타입 마커

TypeScript의 never 타입을 활용한 페이퍼 트레일 패턴입니다. 분석 메타데이터 타입 이름이 AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS로 되어 있으며, 이 타입이 never(바텀 타입)이므로 값을 할당하려면 명시적 as 캐스트가 필요합니다.

// 타입 정의 — never 타입으로 명시적 캐스트 강제
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = never

// 사용 시 — as 캐스트가 코드 리뷰 신호 역할
const metadata = sanitizedValue as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

이 패턴의 의도: as 캐스트를 하려면 개발자가 "이 값이 코드나 파일 경로가 아님을 확인했다"는 타입 이름을 읽어야 합니다. 코드 리뷰어에게도 해당 캐스트의 의미를 즉시 전달합니다.

런타임 보호

• 도구 입력 잘라내기: 도구 호출의 입력값을 512자에서 128자로 잘라내어 전체 내용이 전송되지 않도록 합니다
• MCP 도구 이름 일반화: 외부 MCP 도구 이름은 "mcp_tool"로 일반화되어 도구 이름에 포함될 수 있는 민감한 정보를 제거합니다

GrowthBook은 기능 플래그와 A/B 테스트를 관리하는 시스템입니다. Claude Code는 원격 평가 모드를 사용합니다.

원격 평가

기능 플래그는 로컬에서 평가되지 않고 GrowthBook 서버에서 평가된 결과를 받아옵니다. 복잡한 타겟팅 규칙을 클라이언트에 배포하지 않아도 됩니다.

사용자 속성

원격 평가에 사용되는 주요 사용자 속성:

• deviceID — 기기 식별자
• platform — OS 플랫폼
• subscriptionType — 구독 유형

3레벨 오버라이드

기능 플래그 값은 세 단계에서 오버라이드할 수 있으며, 우선순위가 높은 순서대로 적용됩니다:

1. 환경 변수 — 로컬 개발/테스트용 즉시 오버라이드 (최고 우선순위)
2. 설정 파일 — 사용자 또는 조직 정책에서 오버라이드
3. 원격 (GrowthBook 서버) — 기본 원격 값 (최저 우선순위)

안전 가드와 노출 중복 제거

• 빈 features 객체 보호: GrowthBook 서버 응답의 features 객체가 비어 있으면 디스크 캐시를 보존합니다. 서버 장애 시 마지막 알려진 양호한 설정을 유지합니다.
• 노출 중복 제거: 동일한 기능 플래그에 대한 노출 이벤트가 세션 내에서 중복 기록되지 않도록 합니다.

tengu_frond_boric — 의도적으로 의미 없는 키 이름을 사용하여 우연한 충돌을 방지하는 킬스위치입니다.

독립적 싱크 제어

킬스위치는 Datadog 싱크와 firstParty 싱크를 독립적으로 비활성화할 수 있습니다. 하나의 싱크에 문제가 발생했을 때 다른 싱크에 영향을 주지 않고 개별적으로 끌 수 있습니다.

실패 개방 설계

킬스위치는 실패 개방(fail-open) 설계를 따릅니다:

• 설정이 없거나 GrowthBook이 로드되지 않은 경우 — 싱크 활성 유지
• 킬스위치 설정 읽기에 실패한 경우 — 싱크 활성 유지
• 명시적으로 비활성화 설정된 경우에만 — 싱크 비활성화

킬스위치 외에도 여러 조건에서 분석 시스템이 비활성화됩니다:

• test 환경: 테스트 실행 시 분석 비활성화
• Bedrock: Amazon Bedrock 프로바이더 사용 시
• Vertex: Google Vertex AI 프로바이더 사용 시
• Foundry: Foundry 프로바이더 사용 시
• 텔레메트리 비활성화: 사용자가 설정에서 명시적으로 비활성화한 경우

예외: 피드백 설문

피드백 설문(사용자 만족도 조사 등)은 서드파티 프로바이더(Bedrock, Vertex 등)에서도 활성 상태를 유지합니다. 프로바이더에 관계없이 제품 경험 데이터를 수집하기 위함입니다.

shouldSampleEvent() 함수가 이벤트별 샘플링을 제어합니다.

샘플링 규칙

• 설정 없음 → null 반환: 100% 로깅, sample_rate 메타데이터 없음
• 0 → 드롭: 해당 이벤트 완전 비활성화
• 비율 값 (예: 0.1) → 확률적 샘플링: 10%만 수집하고 sample_rate 메타데이터를 추가하여 역확률 가중치 보정 가능

// shouldSampleEvent() 반환값에 따른 동작
const sampleResult = shouldSampleEvent(eventName)

if (sampleResult === null) {
  // 설정 없음 — 100% 로깅, sample_rate 메타데이터 없음
  dispatch(event)
} else if (sampleResult === 0) {
  // 드롭 — 이 이벤트 타입 완전 비활성화
  return
} else {
  // 확률적 샘플링 — 역확률 가중치용 메타데이터 추가
  event.metadata.sample_rate = sampleResult
  if (Math.random() < sampleResult) {
    dispatch(event)
  }
}