Claude Code 사용을 모니터링하는 3가지 오픈 소스 도구

Vibe Coders에게 Anthropic의 Claude Code와 같은 도구는 많은 엔지니어에게 필수 불가결한 존재가 되었습니다. 상용구 코드 생성부터 복잡한 알고리즘 디버깅에 이르기까지 Claude Code는 생산성을 크게 향상시킬 수 있습니다. 그러나 이러한 강력한 기능에는 감독이 필요합니다. 모니터링되지 않는 사용은 예상치 못한 비용, 성능 병목 현상, 그리고 이러한 강력한 도구가 개발 수명 주기에 미치는 영향에 대한 불완전한 이해로 이어질 수 있습니다.

효과적인 모니터링은 단순히 비용을 추적하는 것을 넘어 가치를 이해하는 것입니다. 현재 작업에 가장 비용 효율적인 모델을 사용하고 있습니까? 워크플로우에서 최적화될 수 있는 패턴이 있습니까? AI 지원이 팀의 실질적인 생산성 향상으로 어떻게 이어지고 있습니까? 이러한 질문에 답하려면 데이터가 필요하며, 바로 이 지점에서 오픈 소스 모니터링 도구가 중요한 역할을 합니다.

Claude Code가 어느 정도의 사용량 정보를 제공하지만, 더 깊고 실행 가능한 통찰력을 제공하기 위한 전용 오픈 소스 도구 생태계가 등장했습니다. 이 도구들은 일일 토큰 소비량을 빠르게 확인하려는 개인 개발자부터 AI 사용량을 중심으로 포괄적인 관측 가능성 플랫폼을 구축하려는 기업 팀에 이르기까지 다양한 요구 사항을 충족합니다.

이 글에서는 Claude Code 사용량을 모니터링하는 데 도움이 되는 세 가지 개별적인 오픈 소스 도구를 심층적으로 살펴보겠습니다:

ccusage: 로컬 사용 데이터를 빠르고 즉각적으로 분석하기 위한 빠르고 간단한 명령줄 인터페이스(CLI)입니다.
Claude-Code-Usage-Monitor: 현재 세션을 파악하고 토큰 한도 초과를 방지하는 데 도움이 되는 대화형 실시간 터미널 대시보드입니다.
claude-code-otel: 팀 전체 사용량, 성능 및 비용을 포괄적으로 장기 모니터링하기 위한 완전한 엔터프라이즈급 관측 가능성 스택입니다.

각 도구의 아키텍처, 기능 및 이상적인 사용 사례를 탐색하여 Claude Code 개발 워크플로우를 마스터하는 데 적합한 도구를 선택하는 데 도움을 드리겠습니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

개발팀이 최대의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog은 모든 요구 사항을 충족하며, 훨씬 더 저렴한 가격으로 Postman을 대체합니다!

button

`ccusage`

속도, 단순성, 효율성을 중시하는 개발자에게 ccusage는 완벽한 도구입니다. GitHub 사용자 ryoppippi가 만든 이 도구는 Claude Code가 생성하는 로컬 JSONL 로그 파일을 분석하여 Claude Code 사용량 및 비용에 대한 명확하고 간결한 보고서를 제공하는 가볍고 매우 빠른 CLI 도구입니다.

주요 기능:

다양한 보고서 보기: `daily`, `monthly`, `session`, `blocks` 보고서(Claude Code의 5시간 청구 주기와 일치)를 통해 질문에 맞춰진 통찰력을 얻으세요.
실시간 모니터링: ccusage blocks --live 명령을 사용하면 활성 세션 진행 상황, 토큰 "소모율(burn rate)", 예상 비용을 보여주는 실시간 대시보드를 얻을 수 있습니다.
비용 및 모델 분석: 이 도구는 단순히 토큰을 계산하는 것을 넘어, 이를 USD로 변환하고 사용한 특정 모델(Opus, Sonnet, Haiku 등)별로 비용을 분류할 수 있습니다.
유연한 출력: 기본적으로 사람이 읽기 쉬운 표는 아름답게 서식 지정되어 터미널 너비에 맞춰 조정되지만, `--json` 플래그를 사용하여 모든 보고서를 JSON으로 내보내 다른 스크립트나 도구에 쉽게 통합할 수 있습니다.
제로 종속성 실행: `npx`를 사용하면 영구 설치 없이 ccusage를 즉시 실행할 수 있어 빠르고 일회성 검사에 이상적입니다.

작동 방식:

ccusage는 TypeScript로 작성된 NodeJS 기반 도구입니다. 이 도구의 마법은 단순성에 있습니다. 로컬 Claude Code 구성 디렉토리(예: ~/.config/claude/logs/)에 저장된 .jsonl 파일을 직접 파싱합니다. 이 이벤트 로그를 읽고, 프롬프트 및 응답에 대한 토큰 수를 집계하며, 각 모델에 대한 최신 가격 정보를 적용하고, 데이터를 깔끔한 표 형식으로 제공합니다. 이러한 로컬 우선 접근 방식은 이 도구가 매우 빠르고 완전히 오프라인으로 작동한다는 것을 의미합니다(가격 데이터를 한 번 캐시한 경우).

설치 및 사용법:

ccusage 시작은 매우 쉽습니다. 설치 없이 바로 실행하려면 다음을 사용하십시오:

npx ccusage@latest

이 명령은 최신 버전을 가져와 일일 보고서를 보여줍니다. 더 자세한 보기를 원하면 보고서 유형을 지정할 수 있습니다:

# 각 월별 사용량 요약 보기
npx ccusage@latest monthly

# 대화 세션별 사용량 그룹화
npx ccusage@latest session --breakdown

# 현재 5시간 청구 블록을 실시간으로 모니터링
npx ccusage@latest blocks --live

누구를 위한 도구인가?

ccusage는 개인 개발자에게 이상적인 도구입니다. 다음 경우에 완벽합니다:

"어제 Claude Code에 얼마를 썼지?"라는 질문에 답하기.
긴 코딩 세션이 끝난 후 토큰 사용량 확인하기.
복잡한 설정의 오버헤드 없이 간단하고 즉각적인 분석 수행하기.
JSON 출력을 통해 사용량 데이터를 다른 스크립트로 파이프하기.

개인 Claude Code 사용량을 빠르고 간편하게 파악하고 싶다면, ccusage는 훌륭한 시작점입니다.

`Claude-Code-Usage-Monitor`

ccusage가 사후 분석에 탁월한 반면, Maciek-roboblog의 Claude-Code-Usage-Monitor는 코딩 세션 중 실시간 동반자가 되도록 설계되었습니다. 이 Python 기반 도구는 사용한 양을 보여줄 뿐만 아니라 앞으로 사용할 양을 예측하여 예상치 못하게 토큰 한도에 도달하는 것을 방지하는 지속적인 실시간 터미널 대시보드를 제공합니다.

주요 기능:

대화형 실시간 대시보드: 모니터는 현재 5시간 세션 창 내에서 토큰 사용량을 지속적으로 업데이트하여 보여줍니다(3초마다).
예측 분석: 이 도구의 뛰어난 기능은 "소모율(burn rate)" 계산입니다. 최근 사용량을 분석하여 세션 토큰이 언제 소진될지 예측하여 속도를 늦출 기회를 제공합니다.
시각적 진행률 표시줄: UI는 풍부하고 직관적이며, 토큰 소비량과 세션 남은 시간에 대한 색상 코딩된 진행률 표시줄을 제공합니다.
요금제 및 시간대 인식: 다양한 Claude Code 요금제(Pro, Max5, Max20)에 맞게 모니터를 구성하고, 정확한 세션 재설정 예측을 위해 현지 시간대를 설정할 수 있습니다. 과거 사용량을 기반으로 요금제를 자동 감지할 수도 있습니다.
경고 시스템: 이 도구는 토큰 한도에 가까워지면 적극적으로 경고하여 사용량을 더욱 능동적으로 관리할 수 있도록 돕습니다.

작동 방식:

ccusage와 유사하게, 이 도구도 로컬 Claude Code 로그 파일을 모니터링합니다. 그러나 단순히 과거 데이터를 보고하는 대신, 현재 5시간 세션의 실시간 상태를 유지합니다. Claude Code의 롤링 윈도우 시스템을 이해하고 그 컨텍스트 내에서 토큰 사용량과 소모율을 계산합니다. Python으로 작성되었으며 rich 라이브러리를 사용하여 세련되고 대화형 터미널 인터페이스를 만듭니다.

설치 및 사용법:

Claude-Code-Usage-Monitor를 설치하는 권장 방법은 가상 환경을 자동으로 처리하는 최신 Python 패키지 설치 도구인 uv를 사용하는 것입니다.

# uv 설치 (없을 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 도구 설치
uv tool install claude-monitor

# 모니터 실행
claude-monitor

일단 실행되면 터미널 창을 차지하고 실시간 대시보드를 표시합니다. 다양한 플래그로 사용자 정의할 수 있습니다:

# 요금제 및 시간대 지정
claude-monitor --plan max20 --timezone America/New_York

누구를 위한 도구인가?

Claude-Code-Usage-Monitor는 작업 중에 지속적으로 정보를 얻고 싶어하는 개발자를 위한 도구입니다. 다음 경우에 완벽합니다:

토큰 한도가 더 엄격하여 신중하게 관리해야 하는 무료 또는 "Pro" 등급 사용자.
사용량을 조절하고 싶은 길고 집중적인 코딩 세션에 참여하는 개발자.
한도에 도달하여 생각 도중에 중단되는 불쾌한 경험을 피하고 싶은 사람.
정적 보고서보다 그래픽 대시보드를 선호하는 시각적 학습자.

토큰 예산의 "수호 천사"처럼 당신을 지켜보고 올바른 길로 이끌어주는 도구를 원한다면, 이것이 바로 당신을 위한 도구입니다.

`claude-code-otel`

앞의 두 도구는 개인 개발자에게 훌륭하지만, 전체 팀이나 조직에서 Claude Code 사용량을 모니터링해야 한다면 어떨까요? 바로 이 지점에서 ColeMurray의 claude-code-otel이 빛을 발합니다. 이것은 단순한 도구가 아니라, 산업 표준 오픈 소스 구성 요소로 구축된 완전한 자체 호스팅 관측 가능성 솔루션입니다.

주요 기능:

전체 관측 가능성 스택: 생산 인프라 모니터링에 사용되는 동일한 강력한 도구인 OpenTelemetry, Prometheus, Loki, Grafana의 사전 구성된 설정을 제공합니다.
포괄적인 대시보드: 이 프로젝트는 비용, 사용자 활동, 도구 성능, 생산성 지표(변경 코드 라인 수 등), API 지연 시간, 오류 등을 심층 분석하기 위한 사전 구축된 Grafana 대시보드를 제공합니다.
팀 전체 모니터링: 여러 사용자의 데이터를 집계하도록 처음부터 설계되어, 팀 또는 프로젝트 수준에서 추세를 확인하고, 핵심 사용자를 식별하며, 비용을 관리할 수 있습니다.
데이터 주권 및 보안: 전체 스택을 직접 호스팅하므로, 잠재적으로 민감한 사용자 프롬프트(로그를 선택한 경우)를 포함한 모든 사용량 데이터가 자체 인프라 내에 유지됩니다.
표준 기반: OpenTelemetry를 사용함으로써, 텔레메트리 데이터에 대한 공급업체 중립적인 표준을 준수하여 확장 가능하고 미래에 대비할 수 있습니다.

작동 방식:

이 솔루션은 근본적으로 다른 접근 방식을 취합니다. Claude Code의 OpenTelemetry(OTel) 내장 지원을 활용합니다. 몇 가지 환경 변수를 설정하여 Claude Code CLI가 상세 메트릭 및 로그를 내보내도록 구성할 수 있습니다. claude-code-otel은 이 데이터를 수신하고 처리하기 위해 전체 백엔드를 실행하는 docker-compose 설정을 제공합니다:

OpenTelemetry Collector: 모든 사용자 Claude Code 인스턴스에서 텔레메트리 데이터를 수신합니다.
Prometheus: 메트릭(예: 토큰 수, 비용, 지연 시간)을 스크랩하고 저장합니다.
Loki: 이벤트 로그(예: 사용자 프롬프트, 도구 결과, API 오류)를 수집하고 저장합니다.
Grafana: Prometheus와 Loki를 쿼리하여 강력하고 대화형 대시보드에서 데이터를 시각화합니다.

설치 및 사용법:

claude-code-otel 설정은 다른 도구보다 복잡하지만, Docker 덕분에 놀랍도록 간소화되었습니다.

저장소 복제:

git clone https://github.com/ColeMurray/claude-code-otel.git
cd claude-code-otel

2. 스택 시작:

make up

3. 환경 변수를 설정하여 로컬 Claude Code 환경이 새 스택으로 데이터를 전송하도록 구성하십시오:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# ... 및 기타 몇 가지

4. 브라우저에서 http://localhost:3000으로 이동하여 대시보드에 액세스하십시오.

누구를 위한 도구인가?

claude-code-otel은 엔지니어링 팀, 플랫폼 팀, 그리고 경영진을 위한 확실한 솔루션입니다. 다음 경우에 이상적입니다:

AI 개발 도구의 ROI(투자 수익률)를 측정하려는 조직.
Claude Code 사용을 위한 공유 예산을 관리해야 하는 팀 리더.
AI 도구의 성능 및 안정성을 모니터링해야 하는 플랫폼 엔지니어.
개발팀 전반에서 AI가 어떻게 사용되는지 이해하기 위한 중앙 집중식의 안전하고 강력한 방법을 필요로 하는 모든 조직.

결론: 당신의 렌즈 선택

Claude Code 사용을 마스터하는 여정은 가시성으로 시작됩니다. 우리가 탐색한 세 가지 도구는 이 강력한 AI 비서와의 상호 작용을 볼 수 있는 다른 렌즈를 제공합니다.

과거 사용량에 대한 일반적인 질문에 대한 답변을 얻는 간단하고 강력하며 빠른 방법을 원한다면 ccusage부터 시작하십시오.
코딩 세션 중 토큰 예산 관리를 반응적 분석에서 능동적, 실시간 관리로 전환하고 싶다면 Claude-Code-Usage-Monitor로 넘어가십시오.
초점이 개별 사용량에서 팀 전체 관측 가능성, 비용 관리 및 성능 분석으로 전환될 때 claude-code-otel을 채택하십시오.

이러한 각 오픈 소스 프로젝트는 개발자 커뮤니티에 대한 훌륭한 기여를 나타내며, 사용자가 AI 기술의 수동적인 소비자가 아닌 능동적이고 정보에 입각한 참여자로 전환하도록 지원합니다. 필요에 맞는 올바른 도구를 선택함으로써 새로운 수준의 제어 및 통찰력을 확보하고, AI 지원 개발 워크플로우에서 최대한의 가치를 얻을 수 있습니다.

💡

button