Claude Code usage tracking by LangWatch

LangWatch: Claude Code 및 AI 에이전트 사용량 추적을 위한 완벽한 솔루션

최근 AI 에이전트와 코딩 보조 도구의 사용이 급증하면서, 개발자와 기업에게 가장 중요한 과제 중 하나는 Claude Code와 같은 도구의 **사용량 추적(Usage Tracking)**과 비용 관리입니다. LangWatch는 이러한 요구를 충족시키기 위해 설계된 LLM 엔지니어링 플랫폼으로, Claude Code뿐만 아니라 Codex, OpenCode, Copilot, Cursor, Pi 등 다양한 AI 에이전트의 활동을 완벽하게 모니터링할 수 있는 기능을 제공합니다.

LangWatch란 무엇인가요? (What's LangWatch)

LangWatch는 AI를 프로덕션 환경에 배포하는 팀을 위해 구축된 LLM 엔지니어링 플랫폼입니다. 이 플랫폼은 AI 에이전트가 수행하는 모든 세션의 전체 트레이스 히스토리를 캡처하여 개발 흐름을 개선하고, 토큰 소비량 및 비용을 투명하게 관리할 수 있게 해줍니다.

특히 Claude Code 사용량 추적에 특화되어 있으며, 사용자가 API를 직접 사용하든 개별/팀 플랜과 같은 구독형 서비스를 사용하든 상관없이 실제 비용과 이론적 비용을 모두 산출해 줍니다. 이를 통해 AI 에이전트가 어디서 토큰을 소모하는지, 어떤 부분에서 오류가 발생하는지 상세히 파악할 수 있습니다.

주요 기능 (Features)

LangWatch는 단순한 로그 기록을 넘어, AI 성능을 최적화하기 위한 다양한 핵심 기능을 제공합니다.

1. 포괄적인 트레이스 및 히스토리 관리

AI 에이전트 세션이 남기는 모든 기록을 플랫폼 고유의 UI에서 확인할 수 있습니다. Bash 명령어 실행, 파일 편집, 스킬 호출, MCP(Model Context Protocol) 호출 등 모든 활동이 스팬(Span) 단위로 기록되며, 각 활동의 지속 시간과 입력 및 출력 상세 내용을 한눈에 볼 수 있습니다.

2. 정밀한 토큰 회계 및 비용 분석

• 이론적 비용 vs 실제 비용: API 응답에서 직접 추출한 정확한 비용 수치를 제공합니다. 개별 또는 팀 플랜을 사용하여 별도의 토큰 비용이 발생하지 않는 경우에도, API 리스트 가격 기준의 이론적 비용을 계산하여 보여줍니다.
• 캐시 히트 추적: 캐시 읽기(Cache Read)와 캐시 쓰기(Cache Write)를 별도의 토큰 클래스로 구분하여 추적합니다. 이는 특히 캐시 활용도가 높은 긴 에이전트 세션에서 비용을 정확하게 산출하는 데 필수적입니다.

3. MCP(Model Context Protocol) 서버 통합

LangWatch MCP 서버는 에이전트가 스스로 자신의 트레이스를 쿼리할 수 있게 합니다. 에이전트는 지난주 실행 기록을 검토하고, 토큰이 어디로 가는지 확인하며, 스스로 워크플로우를 수정하여 효율성을 높일 수 있습니다.

4. 사용자 정의 분석 및 차트

트레이스의 모든 메트릭을 차트로 시각화할 수 있습니다. 병렬 세션 수, 세션당 비용, 사용자 응답 대기 시간 등 원하는 지표를 그래프로 구성하여 운영 인사이트를 얻을 수 있습니다.

5. 세션 인사이트 분석

AI를 활용하여 자신의 트레이스 히스토리를 분석할 수 있습니다. 사용자의 질문 패턴, 가장 도움이 되었던 응답, 세션이 중단되거나 문제가 발생한 패턴 등을 분석하여 기술력을 향상시킬 수 있는 통찰을 제공합니다.

사용 방법 (How to Use)

LangWatch를 사용하여 Claude Code 사용량을 추적하는 방법은 매우 간단합니다.

1. 명령어 실행: 터미널에서 다음 명령어를 실행합니다.

   npx langwatch claude

2. 설정 완료: 이 명령어는 Claude Code의 기본 OpenTelemetry 내보내기 기능을 LangWatch로 자동 구성합니다.
3. 추적 시작: 이후 모든 세션은 모델 턴(Turns), 도구 호출, 토큰 클래스별 사용량, 이론적 비용을 포함한 트레이스로 저장됩니다.

이 OpenTelemetry 기반 방식은 로컬 로그 클린업 후에도 데이터가 유지되며, 여러 대의 기기를 이동하며 작업하더라도 하나의 계정으로 추적 기록이 이어지는 장점이 있습니다.

활용 사례 (Use Case)

• 비용 최적화: AI 에이전트 세션에서 발생하는 토큰 사용량을 분석하여 불필요한 컨텍스트 전달을 줄이고 비용을 절감하고자 할 때.
• 디버깅 및 성능 개선: 에이전트가 특정 도구(Bash, MCP 등)를 호출할 때 발생하는 오류나 지연 시간을 파악하여 시스템 안정성을 높일 때.
• 워크플로우 자동화: MCP 서버 연동을 통해 에이전트가 스스로의 기록을 학습하고 더 효율적인 코딩 전략을 세우도록 유도할 때.
• 보안 및 규정 준수: PII(개인정보) 및 API 비밀 키가 로그에 남지 않도록 자동 가림(Redaction) 기능을 활용하여 엔터프라이즈 보안 요구 사항을 충족할 때.

자주 묻는 질문 (FAQ)

Q: Claude Code 외의 다른 도구와도 호환되나요? A: 네, Codex, OpenCode, Copilot, Cursor, Pi 등 다양한 에이전트와 호환됩니다. 모든 에이전트가 동일한 OTLP 엔드포인트를 통해 데이터를 내보내므로 통합 관리가 가능합니다.

Q: "Bundled" 비용 라벨은 무엇을 의미하나요? A: Claude Pro, Max, Team 플랜과 같이 토큰당 비용이 청구되지 않는 구독형 세션을 의미합니다. LangWatch는 이러한 세션에 대해 API 리스트 가격을 기준으로 이론적인 총액을 계산하여 "만약 API를 사용했다면 비용이 얼마였을지"를 보여줍니다.

Q: 캐시된 토큰도 계산에 포함되나요? A: 네. 캐시 읽기와 캐시 쓰기는 별도의 토큰 클래스로 구분되어 각각의 요율에 따라 가격이 책정됩니다. 긴 세션에서는 캐시 읽기가 큰 비중을 차지하므로, 이를 정확히 구분해야 실제 비용을 제대로 파악할 수 있습니다.

Q: 세션 중에 비밀 키가 유출되면 어떻게 하나요? A: LangWatch는 API 비밀 키와 PII(개인정보)를 자동으로 감지하여 가림 처리(Redact)하며, 서버 측에 저장하지 않습니다. 더욱 강력한 제어가 필요한 경우 엔터프라이즈 정책이나 셀프 호스팅 설정을 사용할 수 있습니다.

---

LangWatch는 개인 사용자에게 무료로 제공되며, 간단한 명령어 한 번으로 AI 에이전트의 효율성을 극대화할 수 있습니다. 지금 바로 시작하여 여러분의 AI 개발 흐름을 투명하게 관리해 보세요.