cctrace¶
Claude Code·Codex CLI 세션용 자체 호스팅 텔레메트리
cctrace는 코딩 에이전트 세션이 실제로 한 일(토큰 사용량, 비용, 도구 호출, 대화 내용)을 직접 운영하는 데이터베이스에 모으고 그 위에 대시보드를 제공한다. 에이전트의 OpenTelemetry 출력으로는 "얼마나"를, 세션 트랜스크립트로는 "무엇을 했나"를 알 수 있다. cctrace는 둘을 모두 수집해 세션 단위로 묶어 둔다.
위 대시보드는 데모 서버 위의 가상 5인 팀이며 실제 운영 데이터가 아니다. 페이지별 설명은 대시보드 페이지 참고.
데이터 수집 경로¶
한쪽만으로는 부족해서 두 경로가 하나의 저장소로 모인다.
| 경로 | 출처 | 전송 | 내용 | 지연 |
|---|---|---|---|---|
| OTEL | 에이전트의 OTLP exporter | gRPC 4317 (Claude Code), HTTP 4318 (Codex) | 토큰 수, 비용, 메트릭 | 실시간 |
| Sync | 디스크의 세션 JSONL 파일 | HTTP /api/sync (포트 8080) |
전체 대화, 도구 호출 | 주기적 |
개발자 머신에서는 cctrace init 하나로 두 경로 모두 설정. 에이전트의 OTLP exporter를 서버로 향하게 하고 동기화 데몬을 띄우는 훅을 등록한다.
구성 요소¶
| 구성 요소 | 실행 위치 | 역할 |
|---|---|---|
cctrace |
각 개발자 머신 | 클라이언트 CLI와 동기화 데몬. 에이전트 세션 디렉터리를 감시해 레코드 업로드 |
cctraced |
서버 호스트 | 서버. OTLP 수신, 동기화 업로드 수신, API·대시보드 제공 |
| TimescaleDB + 대시보드 | 서버 호스트 | 압축·보존 정책이 걸린 저장소. Next.js 대시보드는 cctraced에 내장 |
서버와 데이터베이스는 deploy/docker-compose.yml의 컨테이너 두 개로 실행. 두 이미지 모두 이 저장소에서 빌드하며 레지스트리에 공개된 이미지는 없음.
알아 둘 점¶
- 제3자로 텔레메트리 전송 없음. 지정한 서버 외에, 클라이언트는 요금제 한도를 읽으려고 로컬 Claude Code 로그인으로 Anthropic 사용량 API를 조회하고, 서버는 OpenAI 공개 가격 페이지를 내려받음. 개인정보 참조. 주간 AI 리포트는 관리자가 켜면 외부 AI 제공자로 데이터를 보낼 수 있으나, 변경이 진행 중이라 이 문서에서 다루지 않음
- 호스팅 서비스·사전 빌드 바이너리 없음. 클라이언트와 서버 이미지를 소스에서 빌드
- 이 저장소에서 빌드한 클라이언트는 자동 업데이트 없음. 빈 업데이트 공개 키로 링크되어 자동 업데이트를 거부하므로 업그레이드는 재빌드로 진행
대시보드는 대화 내용을 저장한다. 팀을 연결하기 전에 보존 기간과 마스킹 범위를 먼저 정할 것. 개인정보 참조.
상태
cctrace는 초기 단계. 서버 API와 데이터베이스 스키마가 릴리스마다 바뀔 수 있음. 둘 중 하나에 의존한다면 버전 고정 필요.