Claude Code Observability 플랫폼 구축: AWS 관리형 서비스 활용

1. 개요

• 본 문서는 Claude Code와 같은 AI 코딩 에이전트의 비용, 생산성, 성능 등을 체계적으로 분석하기 위한 Observability 플랫폼 구축 방법을 소개합니다.
• 목표: AWS 관리형 서비스만으로 구성된 이중 파이프라인 아키텍처를 통해 Claude Code의 풍부한 텔레메트리(메트릭, 이벤트)를 수집, 저장, 분석.

2. AI 코딩 에이전트 Observability의 필요성

• AI 코딩 에이전트는 에이전틱 워크플로우 수행으로 기존 소프트웨어 모니터링과 다른 관점의 관측성 필요.
• 핵심 질문: 팀별/사용자별 AI 비용, 모델별 비용 효율, 도구 실행 성공률, 실제 생산성 기여도 등.
• Claude Code는 OpenTelemetry(OTel) 프로토콜로 8종 메트릭과 5종 이벤트 제공.

3. 이중 파이프라인 아키텍처 설계

3.1. 파이프라인 분리 이유

• 메트릭(Metrics): 실시간 집계 및 분석에 최적화 (Prometheus).
• 이벤트(Events): 심층 분석 및 개별 레코드 쿼리에 최적화 (Amazon S3 + Athena).
• 단일 저장소로는 두 가지 요구사항 충족 어려움.

3.2. 전체 아키텍처 구성

• 수집: ADOT Collector (ECS + Fargate) → NLB.
• 메트릭 파이프라인: ADOT → AMP (Amazon Managed Service for Prometheus).
• 이벤트 파이프라인: ADOT → CloudWatch Logs → Lambda Transformer → Amazon Data Firehose → S3 (Parquet) → Athena.
• 시각화: Amazon Managed Grafana.

4. 컴포넌트별 상세 분석

4.1. 수집 계층: ADOT Collector on ECS + Fargate

• OTel Collector의 AWS 배포판으로, 두 파이프라인 동시 운영.
• 설정: prometheusremotewrite (AMP 전송), awscloudwatchlogs (CloudWatch Logs 전송) exporter 설정.
• 주의: Cumulative Temporality 설정 필수.

4.2. 메트릭 파이프라인: AMP

• 8종의 메트릭(세션 수, 비용, 토큰 사용량, 코드 변경량 등)을 Prometheus Remote Write로 AMP에 전송.
• 특징: 실시간 집계, PromQL 쿼리, Grafana 연동으로 실시간 모니터링 제공.

4.3. 이벤트 파이프라인: S3 + Athena

• 데이터 변환: Lambda Transformer가 OTLP JSON을 Glue 스키마 호환 평면 JSON으로 변환.
• 저장: Firehose가 Parquet(Snappy 압축)으로 S3에 저장 (Hive 스타일 파티셔닝).
• 파티션 등록: S3 Event → EventBridge → Lambda → Glue API (실시간 파티션 자동 등록).
• 통합 스키마: 5종 이벤트(prompt, tool_result, api_request/error, tool_decision)를 단일 스키마로 관리.

4.4. 대시보드: Managed Grafana

• 6개 프로덕션 수준 대시보드 (총 80패널) 제공.
• 포함 내용: KPI, 실시간 메트릭, 비용 분석, 사용량/세션 인사이트, 도구 분석, API 성능.
• Prometheus와 Athena 데이터를 결합하여 실시간 모니터링과 이벤트 단위 심층 분석 동시 제공.

5. 결론

• AWS 관리형 서비스 기반의 이중 파이프라인으로 Claude Code 텔레메트리 수집, 저장, 시각화 구현.
• 핵심: 실시간 집계(AMP)와 심층 분석(Athena)을 결합하여 AI 도구 사용 현황에 대한 종합적인 관측성 확보.
• 시작: Claude Code 환경 변수 설정 및 GitHub 리포지토리 활용.