Claude Code 사용량, 비용, 성능을 한눈에 파악하는 AWS Observability 플랫폼 구축
AI 코딩 어시스턴트(AI Coding Assistant) 사용량 및 비용 분석을 위해 관측성(Observability) 플랫폼 구축의 필요성을 제기
Claude Code가 OTel 프로토콜을 통해 세션, 비용, 도구 실행 결과 등 풍부한 텔레메트리(Telemetry)를 내보냄
AWS 관리형 서비스(AWS Managed Services) 기반의 이중 파이프라인 아키텍처(Dual Pipeline Architecture)를 통해 메트릭(Metrics)과 이벤트(Events)를 수집, 저장, 시각화
ADOT Collector, AMP, Athena, Grafana를 활용하여 사용자별 비용 추적, 도구 성공률 분석 등 실질적인 운영 인사이트(Operational Insights) 확보
GitHub 리포지토리(Repository)를 통해 AWS CDK(AWS CDK) 기반의 플랫폼 배포 가능
이중 파이프라인 아키텍처(Dual Pipeline Architecture) 설계
본 아키텍처는 메트릭(Metrics)과 이벤트(Events)의 특성 차이를 고려하여, 각 데이터 유형에 최적화된 저장소를 선택했다.
메트릭 파이프라인: AMP(Amazon Managed Service for Prometheus)를 사용하여 실시간 집계 및 PromQL 쿼리 지원
이벤트 파이프라인: Athena를 활용하여 개별 이벤트에 대한 심층 분석 및 SQL 기반 쿼리 가능
ADOT Collector를 통해 OTel 데이터를 수집하고, Prometheus Remote Write API를 사용하여 AMP로 전송
이러한 이중 파이프라인 구조는 실시간 모니터링(Real-time Monitoring)과 상세 분석(Deep Analysis)을 동시에 가능하게 한다.
ADOT Collector on ECS + Fargate 구성
ADOT Collector는 ECS(Elastic Container Service) + Fargate 환경에서 실행되어, 인프라 관리 부담을 줄였다.
gRPC(4317) 및 HTTP(4318) 프로토콜을 모두 지원하여 클라이언트 환경에 유연하게 대응
Cumulative Temporality 메트릭만 지원하며, delta temporality 메트릭은 삭제되므로 주의 필요
NLB(Network Load Balancer)를 통해 OTLP 트래픽을 수신하며, SigV4 인증을 통해 보안 강화
ADOT Collector는 AWS 서비스와의 네이티브 통합을 제공하여, 손쉬운 Observability 플랫폼 구축을 지원한다.
이벤트 파이프라인: 데이터 변환 및 파티션 관리
이벤트 파이프라인은 OTLP JSON 데이터를 Athena에서 쿼리 가능한 Parquet 형식으로 변환하는 것이 핵심이다.
Lambda Transformer를 사용하여 CloudWatch Logs 엔벨로프 디코딩 및 OTLP JSON을 평면 JSON으로 변환
Firehose는 Glue Data Catalog 스키마를 참조하여 Parquet 형식으로 자동 변환 후 S3에 저장
S3 ObjectCreated 이벤트를 통해 EventBridge를 트리거하고, Lambda가 Glue BatchCreatePartition API를 호출하여 실시간 파티션 등록
이러한 과정을 통해 Athena 쿼리 성능(Query Performance)을 최적화하고, 데이터 분석 효율성을 높였다.
통합 이벤트 스키마(Integrated Event Schema) 설계
5종의 이벤트를 하나의 통합 스키마로 관리하여, 데이터 분석의 유연성(Flexibility)을 확보했다.
event_name 필드를 사용하여 이벤트 유형을 식별하고, 각 이벤트에 해당하지 않는 필드는 NULL 처리
claude_code.user_prompt, claude_code.tool_result, claude_code.api_request, claude_code.api_error, claude_code.tool_decision 등 주요 이벤트 필드 정의
Firehose의 단일 Parquet 변환 설정으로 모든 이벤트를 처리하여, 관리 편의성 증대
통합 스키마는 데이터 분석(Data Analysis)의 효율성을 높이고, 다양한 분석 쿼리를 지원한다.
Grafana 대시보드 구성 및 시각화
Managed Grafana를 사용하여 실시간 모니터링(Real-time Monitoring)과 심층 분석(Deep Analysis)을 위한 대시보드를 구축했다.
Overview, Real-Time Metrics, Cost Deep Analysis, Usage & Session Insights, Tool Analytics, API Performance 등 6개의 대시보드 구성
Prometheus와 Athena를 결합하여, 실시간 메트릭과 이벤트 기반의 상세 정보를 동시에 제공
게이지, 스파크라인, 임계값 색상, 드릴다운 링크 등 다양한 시각화 기법 활용
대시보드는 Claude Code의 사용 현황(Usage Status)을 한눈에 파악하고, 문제 발생 시 신속하게 대응할 수 있도록 돕는다.
