Claude Code 팀 사용량을 OTEL로 추적하는 법 — 메트릭 레이블링과 관측성 아키텍처

메트릭 레이블 하나로 팀별 비용을 가른다

Claude Code는 OpenTelemetry(OTEL) 표준으로 세션·토큰 소비·도구 호출·API 요청을 텔레메트리 데이터로 내보낸다. 이번 업데이트의 핵심은 OTEL_RESOURCE_ATTRIBUTES에 지정한 값이 이제 메트릭 데이터포인트의 레이블로 직접 포함된다는 점이다. 예전에는 리소스 속성이 스팬(span) 메타데이터에만 기록돼 메트릭 집계 시 필터로 쓰기 어려웠다.

# 팀별 메트릭 레이블링 예시
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123,repository=api-gateway"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.your-company.com:4317"

이 설정만으로 Grafana, Prometheus, Elastic, VictoriaMetrics 같은 표준 메트릭 백엔드에서 team.id나 cost_center 기준으로 사용량을 그룹핑·필터링할 수 있다. 다만 OpenTelemetry 리소스 속성은 포맷 규칙이 엄격하다. 쉼표로 구분된 key=value 쌍이어야 하고, 값에 공백이 들어가면 안 되며(언더스코어나 하이픈으로 대체), US-ASCII 문자만 허용된다(제어 문자·공백·큰따옴표·쉼표·세미콜론·백슬래시 제외). 키는 소문자를 쓰고 점(.)으로 네임스페이스를 구분하는 편이 관례다.

# 올바른 예
export OTEL_RESOURCE_ATTRIBUTES="team.name=backend-platform,env=production,cost_center=cc-042"

# 잘못된 예 (값에 공백 포함)
export OTEL_RESOURCE_ATTRIBUTES="team.name=backend platform"  # 오류

중규모 엔지니어링 조직이 이 레이블을 수집·집계·시각화하는 전형적인 구조는 다음과 같다.

⤢✕

Claude Code가 OTEL로 내보내는 핵심 메트릭은 입력·출력 토큰 수(claude_code.input_tokens / output_tokens), API 응답 시간(api_request_duration), 도구 호출 횟수(tool_invocations), 세션 지속 시간(session_duration), 추정 비용(cost_usd)이다. Grafana에서 이 레이블을 PromQL로 조합하면 팀별 일일 토큰 소비량을 바로 뽑아낼 수 있다.

# 팀별 일일 토큰 소비량 (PromQL)
sum by (team_id) (
  increase(claude_code_input_tokens_total[1d])
  + increase(claude_code_output_tokens_total[1d])
)

2026년 기준 엔터프라이즈 Claude Code 도입 시 개발자 1인당 월 평균 비용은 150~~250달러 수준으로 보고된다. 팀 규모가 50명이면 월 7,500~~12,500달러 규모가 되므로, 팀·비용센터별 세분화 추적은 재무 거버넌스 관점에서 필수에 가깝다.

에이전트 팬아웃, 몇 개가 돌고 있는지 보인다

에이전트 팬아웃(Agent Fanout)은 오케스트레이터 에이전트가 Task 도구로 다수의 서브에이전트를 병렬 생성·실행하는 패턴으로, 대규모 리팩토링이나 다중 파일 분석, 병렬 테스트 실행에 쓰인다. 기존에는 팬아웃이 진행되는 동안 내부에서 몇 개의 서브에이전트가 동작 중인지 외부에서 확인하기 어려웠다. GitHub 이슈 #27916에서 커뮤니티가 요청했던 이 기능이 이번 업데이트로 반영돼, CLI 상태 줄에 완료/전체 형태의 카운터가 표시된다. 예컨대 20개 서브에이전트 중 13개가 끝난 시점이면 13/20 agents done처럼 나타난다.

⤢✕

2026년 5월 28일 출시된 Dynamic Workflows와 결합하면 가시성이 더 좋아진다. /workflows 명령으로 실행 중인 워크플로우를 모니터링하면 단계별 진행 상태(계획→실행→검증), 동시 실행 중인 서브에이전트 수, 단계별 누적 토큰 소비량을 확인하고 일시정지·재개·저장을 제어할 수 있다. 단일 워크플로우는 최대 1,000개의 서브에이전트를 지원하며 동시 실행 상한은 16개다. 2026년 5월 출시된 Agent View는 실행 중인 모든 Claude Code 세션을 하나의 대시보드에서 관리하게 해준다 — 팬아웃된 서브에이전트 각각의 상태(대기·실행·완료), 토큰 사용량, 경과 시간이 한눈에 표시되고, 특정 에이전트에 인라인으로 응답하거나 새 에이전트를 파견하는 작업도 같은 화면에서 처리된다.

Linux 클립보드: wl-copy·xclip·xsel 공식 지원

2026년 6월 2일 릴리스를 기점으로 Claude Code 풀스크린 모드에서 Linux 클립보드 통합이 개선됐다. Wayland 환경에서는 wl-copy/wl-paste(wl-clipboard 패키지), X11 환경에서는 xclip 또는 xsel을 쓴다. 클립보드와 PRIMARY 선택 영역(미들 클릭 붙여넣기)을 동시에 복사하도록 지원하고, 터미널 환경에 따라 올바른 단축키를 안내한다.

# Wayland (GNOME, KDE Plasma 6 등)
sudo apt install wl-clipboard     # Ubuntu/Debian
sudo dnf install wl-clipboard     # Fedora
sudo pacman -S wl-clipboard       # Arch Linux

# X11
sudo apt install xclip xsel       # Ubuntu/Debian
sudo dnf install xclip xsel       # Fedora
sudo pacman -S xclip xsel         # Arch Linux

# WSL2 (Windows Subsystem for Linux)
# clip.exe 내장 — 별도 설치 불필요
# 단, 이미지 붙여넣기는 PowerShell 폴백 경로 사용

클립보드 도구 감지 흐름은 운영체제와 데스크탑 환경을 순서대로 확인하는 방식이다.

⤢✕

이전에는 xclip이나 wl-paste가 설치돼 있지 않으면 "No image found in clipboard"라는, 원인을 오해하게 만드는 오류 메시지가 떴다. 이제는 실제 원인(클립보드 도구 미설치)을 정확히 알려준다. WSL2 환경에서는 Windows 클립보드의 이미지를 읽어올 때 xclip/wl-paste를 쓸 수 없으므로 PowerShell 폴백 경로가 자동으로 활성화돼, WSL2 사용자도 Windows에서 복사한 스크린샷을 Claude Code에 바로 붙여넣을 수 있다.

수집한 메트릭을 비용 절감으로 연결하기

OTEL 기반 추적이 의미가 있으려면 수집한 데이터를 실제 비용 최적화 행동으로 이어야 한다. 비용 이상이 감지됐을 때 원인별로 대응 전략이 갈린다 — 특정 팀의 과다 사용이면 관리 설정으로 팀별 사용 한도를 걸고, 비효율적인 프롬프트 패턴이면 캐시 활용을 강화한 프롬프트 템플릿으로 정리하고, 컨텍스트가 과도하게 누적됐다면 /compact 자동화 같은 컨텍스트 압축 정책을 적용하고, 중복 API 호출이 문제라면 Prompt Cache 활성화로 캐싱 전략을 재검토한다.

⤢✕

조직 관리자는 settings.json의 requiredMinimumVersion / requiredMaximumVersion 필드로 허용 버전 범위를 강제할 수 있고, OTEL 관련 설정도 같은 관리형 설정으로 배포하면 모든 개발자 환경에 동일한 OTEL_RESOURCE_ATTRIBUTES가 적용된다.

{
  "requiredMinimumVersion": "1.8.0",
  "env": {
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.internal.company.com:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "org=acme,env=production"
  }
}

이렇게 CDM(Configuration Distribution Mechanism)으로 배포하면 개별 개발자가 환경 변수를 직접 설정할 필요 없이 조직 전체가 통일된 메트릭 레이블 체계를 유지한다.

Enterprise Analytics API와는 어떻게 다른가

Anthropic은 별도로 Enterprise Analytics API를 제공한다. 조직 단위 일별 집계 메트릭(최대 90일 이력)을 반환하며, Claude Code 사용자 기준으로는 커밋 수, 풀 리퀘스트, 추가/삭제 코드 라인 수, 세션 카운트 같은 개발자 생산성 지표를 포함한다. OTEL 자체 수집과는 상호 보완적인 관계다.

구분	OTEL 자체 수집	Enterprise Analytics API
실시간성	실시간 (초 단위)	일별 집계
커스터마이징	자유로운 레이블·필터	고정 스키마
인프라 비용	OTEL Collector 운영 필요	API 호출만으로 가능
데이터 세분화	팀·저장소·비용센터 등	조직 단위
보안	자체 인프라 내 보관	Anthropic 서버

엔터프라이즈 AI 코딩 도구 도입은 비용 가시성(개발자·팀·저장소별 비용 측정과 예산 대비 실적 추적), 보안 컴플라이언스(AI 에이전트가 접근하는 파일·실행 명령·외부 전송 컨텍스트 감사), 생산성 측정(투자가 실제 개발 속도·코드 품질로 이어지는지 정량 검증)이라는 세 과제로 압축된다. OTEL 레이블링은 첫 번째 과제의 기술적 해법이고, OTEL 트레이싱이 모든 도구 호출을 스팬으로 남기는 것은 두 번째 과제를 뒷받침하며, Agent View와 OTEL 메트릭을 결합해 세션 길이·태스크 완료율·서브에이전트 활용도 같은 지표를 구성하면 세 번째 과제에 쓸 수 있다.

Claude Code의 OTEL 내보내기는 옵트인(opt-in) 방식이라 명시적 설정 없이는 외부 엔드포인트로 데이터가 전송되지 않는다. 메트릭과 이벤트에는 원시 파일 내용이나 코드 스니펫이 포함되지 않지만, 스팬 속성에 파일명이나 경로가 담길 수 있으므로 기밀 저장소 이름이 노출되지 않도록 OTEL Collector 단에서 필터링 정책을 적용하는 편이 안전하다.