■ 비용 급증 추적
표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법
왜 배우나 — 시험이 요구하는 것
시험 목표 4.6 로깅과 관측으로 감시 · D4 평가 16%Monitor system performance using logging and observability tools
이 개념으로 푸는 판단 (할 수 있어야 하는 것)
- 4.6① 비용 급증 알림이 떴다 — 대시보드만 보면 원인이 나오나? (빈 목표) — 모니터링(무엇이 움직였나)과 관측(왜 — 실행 추적)을 구분해 쓰기
- 1.6③ 한 건에 얼마, 한 달에 얼마? — 비용 축을 숫자로 — 요청당 비용으로 설계안 비교
- 3.4① 수천 세션 중 일부만 30초씩 걸린다 — 모델 호출인지 CRM 도구인지 무엇으로 찾나? — 관측 신호 고르기 (메트릭 · 로그 이벤트 · 트레이스)
한눈에
비용 알림·대시보드 합계는 "얼마가 움직였나" 만 말한다. 원인은 아래 차례로 좁힌다.
- 어디서 : 차원(워크스페이스 · API 키 · 모델 · 서비스 티어 · 속도 · 지역)으로 쪼갠다
- 무엇이 : 토큰 종류(캐시 안 된 입력 · 캐시 읽기 · 캐시 생성 · 출력)로 쪼갠다
- 왜 : 그 실행의 요청
usage와 트레이스를 본다
순서는 알림, 쪼개기, 해당 실행, 원인이다 (도구는 확인, 순서 자체는 업계 일반)
조직 단위 도구는 Usage & Cost Admin API 다. Console 의 Usage·Cost 페이지와 같은 데이터를 프로그램으로 받는다(Admin API 키)
비유 클라우드 청구 급증과 같다. Cost Explorer 로 계정·서비스·태그별로 쪼갠다. 늘어난 줄의 사용 유형(데이터 전송·스토리지)을 본다. 그리고 CloudTrail·X-Ray 로 그 호출을 찾는다
ELI5
전기 요금이 갑자기 많이 나온 집이에요.
- 요금 고지서 합계만 봐서는 어느 방이 범인인지 몰라요.
- 방마다 계량기를 보면 "어디서" 늘었는지 알아요.
- 그 방에서 에어컨인지 전등인지 보면 "무엇이" 늘었는지 알아요.
- 이 쪽은 "합계는 같은데 요금이 오르는 때" 같은 까다로운 경우를 모아 둔 곳이에요.
개념 설명
원리
모니터링과 추적은 다른 질문에 답한다
- 알림·대시보드 합계는 "얼마가 움직였나" 에 답한다. 원인은 알려 주지 않는다.
- 차원별로 쪼개면 "어디서" 가 보인다(워크스페이스 · API 키 · 모델 · 서비스 티어 · 속도 · 지역).
- 토큰 종류로 쪼개면 "무엇이" 가 보인다(캐시 안 된 입력 · 캐시 읽기 · 캐시 생성 · 출력).
- 요청 한 건의
usage와 트레이스는 "왜" 에 답한다(어느 단계·어느 설정).
비용 = 토큰 수 × 단가
- 비용이 오르는 길은 둘이다. 토큰이 늘거나(요청 수 · 입력 · 출력 · 캐시 깨짐), 단가가 오른다(모델 · fast mode · 미국 전용 추론).
- 그래서 토큰 그래프가 멀쩡해도 비용이 오를 수 있다. 토큰이 늘어도 비용이 줄 수 있다.
데이터의 한계
- 조직 데이터는 보통 요청이 끝나고 5분 안에 반영된다(가끔 더 늦다). Cost API 는 하루 단위만 있다.
- 실제 청구액은 Console 등 제공자 기준이다. Claude Code 의 비용 메트릭은 근사치다.
핵심 질문 두 개
- 토큰이 늘었나, 단가가 올랐나?
- 토큰이 늘었다면 어느 종류(캐시 읽기·생성·일반 입력·출력)가 늘었나? 어느 차원에서 늘었나?
규칙과 판단
갈림길
①③⑤ 어느 도구 [4.6①]
Usage API
usage_report/messages 를 쓴다. 모델 · 워크스페이스 · 서비스 티어 등으로 거르고 묶는다. 시간 버킷은 1m·1h·1d 다
Cost API
cost_report 를 쓴다. USD 로 나오고 워크스페이스·description 으로 묶는다. 시간 버킷은 1d 만 있다
응답 usage
input_tokens · cache_creation_input_tokens · cache_read_input_tokens · 출력을 본다
트레이스
자세한 것은 ■ observability 세 신호 에 있다
Claude Code Analytics API
사용자별 예상 비용과 생산성 지표를 준다
② 무엇이 늘었나 [4.6①] [1.6③]
트래픽 · 루프
쓰는 곳이 늘었는지 본다(워크스페이스·API 키). 에이전트 구조가 바뀌었는지도 본다 (◆ 단일 vs 멀티 에이전트) 업계 일반
캐시가 깨졌다
앞부분에 매번 바뀌는 값(날짜 등)이 있는지, thinking·effort 설정이 바뀌었는지, 수명이 지났는지 본다 (■ 프롬프트 캐싱)
답 길이 · effort · max_tokens 부터 본다
답 길이, 높은 effort, max_tokens 를 본다 (■ max_tokens 와 긴 출력)
단가 쪽
fast mode(speed)를 켰는지, 미국 전용 추론 1.1배(inference_geo)인지, 모델이 바뀌었는지 본다
④⑤ 숫자가 안 맞을 때 [4.6①]
실제 청구액은 Console 등 제공자 기준이다
Claude Code 비용 메트릭은 근사치다
반영 지연
보통 요청이 끝나고 5분 안에 반영된다. 가끔 더 늦는다
사용량 쪽에서 본다
Cost API 에는 없다. Usage API 의 service_tier = priority 로 본다
기본 워크스페이스 · 플레이그라운드
기본 워크스페이스는 workspace_id 가 null 이다. 콘솔 플레이그라운드는 api_key_id 가 null 이다
나머지 규칙
-
원인을 찾으려고 프롬프트·응답 원문을 기본으로 다 남기지 않는다. 기본은 구조만 남긴다 (■ 텔레메트리 기록 범위)
규칙 원문 ①②③④⑤ (갈림길로 그린 규칙)
-
조직 단위로는 Usage & Cost Admin API 를 쓴다 (Admin API 키
sk-ant-admin01-...) [4.6①]엔드포인트 단위 거르기·묶기 시간 버킷 /v1/organizations/ usage_ report/ messages 토큰 API 키 · 워크스페이스 · 모델 · 서비스 티어 · 컨텍스트 창 · 데이터 레지던시( inference_) · 속도(geo speed, 베타)1m·1h·1d/v1/organizations/ cost_ report USD 워크스페이스 · description(모델 · inference_파싱)geo 1d만토큰 종류를 따로 센다. 캐시 안 된 입력·캐시된 입력·캐시 생성·출력이다. 웹 검색 등 서버 도구 사용도 센다
Enterprise 조직(claude.ai)은 Admin API 키가 없다. 그래서 Enterprise Analytics API 키를 쓴다
-
늘어난 줄마다 먼저 볼 곳은 아래 표와 같다 (각 원인 =, 짝짓기 자체는 업계 일반) [4.6①] [1.6③]
늘어난 것 먼저 볼 곳 캐시 읽기 ↓ · 캐시 생성·일반 입력 ↑ 캐시가 깨졌다. 앞부분에 매번 바뀌는 값(날짜 등), thinking·effort 설정 변경(메시지 캐시 무효화), 수명 경과를 본다 (■ 프롬프트 캐싱) 출력 ↑ 답 길이 · 높은 effort · max_(■ max_tokens 와 긴 출력)tokens 특정 모델 ↑ 라우팅·기본 모델이 바뀌었다. 새 토크나이저는 같은 글을 약 30% 더 센다 (■ per-request cost) speed= fast ↑fast mode 요금이다 (Opus 5.5 $8/$40, 표준의 2배) inference_= us ↑geo 모든 토큰이 1.1배다 특정 워크스페이스·API 키 ↑ 그 팀·서비스로 좁혀 요청 단위로 본다 요청 수 ↑ 트래픽 · 에이전트 구조 (에이전트 약 4배 · 멀티 약 15배, 채팅 대비. ◆ 단일 vs 멀티 에이전트) -
요청 한 건 : 응답
usage를 본다(스트리밍이면message_start). 입력 필드는 셋이다input_tokens: 캐시에서 읽지도, 캐시에 쓰지도 않은 입력이다(마지막 break point 뒤)cache_creation_input_tokenscache_read_input_tokens
어느 단계(검색(retrieval)·도구·생성)가 토큰을 먹었는지는 트레이스로 본다. 자세한 것은 ■ observability 세 신호 에 있다
-
숫자 믿기 : 숫자를 읽을 때 아래를 알아 둔다
- 실제 청구액은 Console 등 제공자 기준이다. Claude Code 비용 메트릭은 근사치다
- 반영은 보통 5분 안에 된다(가끔 더 늦다)
- 폴링은 분당 1회가 지속 사용 기준이다. 대시보드는 결과를 캐시한다
- Priority Tier 비용은 Cost API 에 없다. Usage API
service_tier로 본다 - 코드 실행은 Cost API 에만 있다(
Code Execution Usage)
-
누가 썼나 : 아래처럼 가린다
- Claude Code 사용자별 비용은 Claude Code Analytics API 로 본다
- 키가 많은 일반 API 는 Usage API 토큰을 비용 대용으로 쓴다
- Claude Code 메트릭은
skill.name·plugin.name·agent.name으로 지출을 스킬·플러그인·서브에이전트에 귀속한다. 흔한 알림은 비용 급증과 이상한 토큰 소비다 - 기본 워크스페이스는
workspace_id가 null 이다. 플레이그라운드는api_key_id가 null 이다
더 깊이 : 판단 규칙 · 상황 변수 (설명)
판단 규칙
| 조건 | 답 | 근거 |
|---|---|---|
| 조직 토큰을 모델·워크스페이스·서비스 티어별로 보려 한다 | Usage API usage_ 를 쓴다 | usage-cost-api "Track token consumption across your organization with detailed breakdowns by model, workspace, and service tier" |
| 토큰을 종류별로 보려 한다 | 캐시 안 된 입력 · 캐시된 입력 · 캐시 생성 · 출력을 따로 본다 | usage-cost-api |
| 더 좁히려 한다 | API 키 · 워크스페이스 · 모델 · 서비스 티어 · 컨텍스트 창 · 데이터 레지던시 · 속도로 거르고 묶는다 | usage-cost-api |
| 달러로 보거나 부서별로 청구를 나누려 한다 | Cost API cost_ 를 쓴다 (USD, 1d 만) | usage-cost-api |
| 요청 한 건을 본다 | 응답 usage 의 세 입력 필드와 출력을 본다 | prompt-caching |
| 캐시 읽기가 0 으로 떨어졌다 (전에는 적중) | thinking·effort 설정 변경을 의심한다 | thinking-troubleshooting |
| Priority Tier 비용을 본다 | Usage API service_ = priority 로 본다 (Cost API 에는 없다) | usage-cost-api |
| Claude Code 사용자별 비용을 본다 | Claude Code Analytics API 를 쓴다 | usage-cost-api |
| Claude Code 비용 메트릭을 청구에 쓰려 한다 | 쓰지 않는다. 근사치다 | monitoring-usage |
| 스킬·플러그인·서브에이전트별 지출을 본다 (Claude Code) | skill. · plugin. · agent. 속성으로 본다 | monitoring-usage |
| Enterprise(claude.ai) 조직이다 | Analytics API 키를 쓴다 (Admin API 키는 없다) | usage-cost-api |
상황 변수
| 변수 | 값 | 답 쪽 | 등급 | 근거 |
|---|---|---|---|---|
| 요청 수 | 늘었다 | 트래픽이나 에이전트 구조 변화를 본다 | 업계 일반 | ◆ 단일 vs 멀티 에이전트(에이전트 약 4배 · 멀티 약 15배) |
| 캐시 읽기 · 생성 | 읽기 ↓ 생성 ↑ | 캐시가 깨졌다 | 계산 | 뒤집히는 때 1 |
| 토큰 | 그대로인데 비용 ↑ | 단가 쪽을 본다 (speed · inference_ · 모델) | 계산 | 뒤집히는 때 2 |
| 토큰 | 늘었는데 모델을 옮긴 직후다 | 새 토크나이저일 수 있다. 비용은 오히려 줄 수도 있다 | 계산 | 뒤집히는 때 3 |
| 급증 시각 | 방금이다 (5분 안) | Usage API 에 아직 없을 수 있다. 요청 usage 와 앱 로그를 본다 | 업계 일반 | 뒤집히는 때 4 |
| 도구 | Claude Code 팀 사용 | Claude Code Analytics API 와 OTel 비용 메트릭(근사치)을 쓴다 | usage-cost-api · monitoring-usage | |
| 서비스 티어 | Priority | Usage API 로만 본다 | usage-cost-api | |
| 비용 종류 | 코드 실행 | Cost API 의 Code Execution Usage 로만 본다 | usage-cost-api | |
| 워크스페이스 | 기본 | workspace_ 가 null 이다 | usage-cost-api |
연습 문제
고객지원 Agent 의 하루 비용이 요청 수는 하루 3만 건 그대로인데요청 수 그대로 약 6배로 뛰었다. Usage API 를 토큰 종류로 쪼개 보니 캐시 읽기는 0 근처로 떨어지고 캐시 생성이 튀었다캐시 읽기 ↓. 팀원은 알림 임계값을 더 촘촘히 걸자고 한다. 원인은 어디부터 볼까?
시험 대비
함정
- "대시보드(메트릭) 합계만 보면 원인이 나온다" 는 함정이다. 합계는 '얼마가' 만 답한다. '어디서·왜' 는 쪼개기와 트레이스가 답한다
- "알림 임계값을 더 촘촘히 건다" 는 함정이다. 알림이 늘 뿐 원인은 그대로다 업계 일반
- "모든 프롬프트·응답 원문을 기본 저장해 두고 뒤진다" 는 함정이다. 기본은 구조만 남긴다. 승인된 파이프라인만 쓴다 (■ 텔레메트리 기록 범위)
- 캐시 적중이 무너진 급증을 "트래픽 증가" 로 보는 것은 함정이다. 요청 수는 그대로이고 캐시 읽기 ↓ 생성 ↑ 면 캐시가 깨진 것이다
- Claude Code 비용 메트릭을 청구 근거로 쓰는 것은 함정이다. 근사치다. 청구는 Console 등을 기준으로 한다
- Cost API 로 Priority Tier 비용을 찾는 것은 함정이다. 거기에는 없다. Usage API
service_tier로 본다 - 방금 뜬 급증이 API 에 안 보인다고 "오탐" 으로 보는 것은 함정이다. 반영은 보통 5분 안에 된다. 더 늦을 수 있다
- 토큰이 그대로라고 "비용 변화 없음" 으로 닫는 것은 함정이다. 단가 쪽(fast · 미국 전용 1.1배 · 모델)도 본다
신호
"Track token consumption across your organization with detailed breakdowns by model, workspace, and service tier"
"Measure uncached input, cached input, cache creation, and output tokens"
"Filter by API key, workspace, model, service tier, context window, data residency, or speed (beta), and group results by these dimensions"
"Usage and cost data typically appears within 5 minutes of API request completion, though delays may occasionally be longer."
"Cost metrics are approximations. For official billing data, refer to your API provider"
"Priority Tier costs are not available in the cost endpoint."
"cache_read_input_tokens falls to zero on requests that previously hit the cache."
더 깊이 : 뒤집히는 때 · 오답 재료 (설명)
뒤집히는 때
1. "비용이 급증 = 트래픽이 늘었다" 가 틀리는 때 — 캐시가 깨짐
- 조건 : Sonnet 5 를 쓴다. 고정 앞부분 1만 2천 토큰, 질문 400, 출력 250, 하루 3만 요청이다. 요청 수는 그대로인데 하루 비용이 급증했다.
- 계산 (백만 토큰당 입력 $2 · 출력 $10 · 5분 쓰기 $2.50 · 읽기 $0.20) :
- 적중 때 = 12,000 × $0.20 + 400 × $2 + 250 × $10 = $0.0024 + $0.0008 + $0.0025 = $0.0057 이다. 하루 $171 이다.
- 매번 새로 쓰기 = 12,000 × $2.50 + $0.0008 + $0.0025 = $0.0333 이다. 하루 $999 다(약 5.8배).
- 판단 : 요청 수와 출력이 그대로면 트래픽 문제가 아니다. Usage API 를 토큰 종류로 쪼개면 캐시 읽기가 0 근처다. 캐시 생성은 하루 약 3억 6천만 토큰으로 튄다. 그래서 캐시가 깨진 것이다. 먼저 볼 것은 둘이다.
- 최근 thinking·effort 설정을 바꿨나?
- 앞부분에 날짜 같은 바뀌는 값이 들어갔나?
- 전제 : 요청마다 캐시 쓰기가 일어난다고 봤다(호출 간격이 수명 안이다). 가격은 2026-09-28 조회값이다.
- 등급 : 계산 (배수·증상·원인은 확인)
- 근거 : prompt-caching 표 · usage-cost-api · thinking-troubleshooting
2. 토큰 그래프는 그대로인데 비용이 오르는 때
- 조건 : Opus 5.5 를 쓴다. 월 입력 2억, 출력 3천만 토큰이다. 토큰 수는 지난달과 같다.
- 계산 :
- 표준 = 200 × $4 + 30 × $20 = $800 + $600 = $1,400
- 미국 전용 추론(
inference_geo: "us")은 × 1.1 이라 $1,540 이다. - fast mode = 200 × $8 + 30 × $40 = $2,800 (2배)
- 둘 다면 × 1.1 이라 $3,080 이다(fast mode 에도 지역 배수가 곱해진다).
- 판단 : 토큰만 보면 "변화 없음" 이다. Usage API 를
speed·inference_geo· 모델로 묶어야 보인다. 누가 fast mode 를 켰는지는 워크스페이스·API 키로 좁힌다. - 등급 : 계산 (단가·배수는 확인)
- 근거 : pricing · usage-cost-api
3. 토큰 알림이 울렸는데 비용은 준 때 — 모델 이관
- 조건 : Sonnet 4.6($3/$15)에서 Sonnet 5($2/$10)로 옮겼다. 새 토크나이저는 같은 글을 약 30% 더 센다. 지난달은 입력 1억, 출력 2천만이었다.
- 계산 :
- 이관 전 = 100 × $3 + 20 × $15 = $300 + $300 = $600
- 이관 뒤 = 130 × $2 + 26 × $10 = $260 + $260 = $520 (토큰은 30% 늘고 비용은 약 13% 준다)
- 판단 : 토큰 수 알림만 걸어 두면 "급증" 으로 오판한다. 비용은 Cost API(USD)로 본다. 토큰은 모델별로 나눠 같이 본다.
- 전제 : 출력도 같은 비율로 30% 늘었다고 봤다(내용에 따라 다르다). 가격은 2026-09-28 조회값이다.
- 등급 : 계산
- 근거 : 릴리스 노트 · prompt-caching 표
4. 방금 뜬 급증이 조직 데이터에 안 보이는 때
- 조건 : 알림이 3분 전에 떴다. 그런데 Usage API 에는 아직 없다.
- 판단 : 반영은 보통 요청이 끝나고 5분 안에 된다. 가끔 더 늦는다. 그래서 "오탐" 으로 닫지 않는다. 기다리는 동안은 내 앱이 남긴 요청
usage(응답마다 온다)로 본다 (앱 쪽 계측은 업계 일반). 폴링은 분당 1회가 지속 사용 기준이다. - 등급 : (5분 · 분당 1회) · 업계 일반 (앱 쪽 계측)
- 근거 : usage-cost-api · prompt-caching
5. 사용자·스킬별로 나눠야 하는 때
- 조건 : 사내 개발자 수백 명이 Claude Code 를 쓴다. 비용이 누구에게서, 어느 스킬에서 늘었는지 알아야 한다.
- 판단 : API 키를 사람마다 나눠 Usage API 로 쪼개는 것은 느리다. 그래서 Claude Code Analytics API(사용자별 예상 비용)를 쓴다. OTel 비용 메트릭은
skill.name·plugin.name·agent.name으로 귀속한다. 다만 근사치라 실제 청구액은 Console 기준이다. - 근거 : usage-cost-api · monitoring-usage
오답 재료
| 오답 | 왜 끌리나 | 왜 틀리나 | 등급 | 근거 |
|---|---|---|---|---|
| "비용 대시보드를 보면 원인이 나온다" | 숫자가 다 있어 보인다 | 합계는 얼마가 움직였는지만 말한다. 차원과 토큰 종류로 쪼개고 해당 실행을 봐야 한다 | usage-cost-api · ■ observability 세 신호 | |
| "알림 임계값을 더 촘촘히" | 빨리 알면 해결될 것 같다 | 알림만 늘고 원인은 그대로다 | 업계 일반 | 목록 4.6① "매력적인 오답" |
| "모든 프롬프트·응답 원문을 기본 저장해 두고 뒤진다" | 다 있으면 안심이 된다 | 기본은 구조만 남긴다. 승인된 파이프라인만 쓴다. 규제 환경이면 보존 문제가 생긴다 | ■ 텔레메트리 기록 범위 · monitoring-usage | |
| "요청 수가 그대로니 비용 급증은 오류" | 트래픽만 원인으로 본다 | 캐시가 깨지면 요청 수가 그대로여도 약 5.8배가 된다 | 계산 | 뒤집히는 때 1 |
| "토큰이 그대로면 비용도 그대로" | 비용 = 토큰으로 외웠다 | fast mode 2배 · 미국 전용 1.1배 · 모델 단가가 있다 | 계산 | 뒤집히는 때 2 |
| "토큰이 30% 늘었으니 비용 급증" | 토큰 알림이 울렸다 | 새 토크나이저 이관이면 비용은 줄 수도 있다 | 계산 | 뒤집히는 때 3 |
| "Claude Code 비용 메트릭으로 부서에 청구" | 숫자가 USD 로 나온다 | 근사치다. 실제 청구액은 제공자 기준이다 | monitoring-usage | |
| "Cost API 로 Priority Tier 비용을 본다" | 비용이니 Cost API 라고 생각한다 | Cost API 에는 없다. Usage API service_ 로 본다 | usage-cost-api |
참고
더 깊이 : 출처 · 상태 · 미해결 (참고)
출처
- 가이드 목표 4.6 공식 시험 가이드 v1.0
- usage-cost-api
- prompt-caching
- thinking-troubleshooting
- pricing
- monitoring-usage
- 릴리스 노트
- multi-agent-research-system
상태
- 업계 일반 3줄(조사 순서 · ② 짝짓기 · 임계값 함정)
미해결
- 목록 4.6① 의 "root trace 아래 검색·도구·생성 span, 토큰·지연·TTFT·stop_reason·도구 호출" 필드 목록은 목록 스스로 "영상 기준 — 근거 확인 필요" 라고 적었다. 직접 API 앱용 공식 필드 목록은 받은 원문에 없다. 그래서 카드는 Claude Code·Agent SDK 트레이스(■ observability 세 신호)를 가리키기만 한다.
- Usage API 가 요청 수(건수)를 주는지 모른다. 받은 원문 key concepts 에는 토큰만 있다(usage-cost-api). 그래서 카드는 요청 수를 앱·게이트웨이 로그로 본다(업계 일반).
- Cost API 의
description묶음에서 fast mode·Priority 가 어떻게 찍히는지 모른다. 원문에는model·inference_geo파싱만 나온다. - 영어 신호 "User prompt content is not collected by default. Only prompt length is recorded." 는 monitoring-usage에 있다. 본문은 ■ 텔레메트리 기록 범위 에 있으므로 여기서는 인용하지 않는다.