세션 검사 및 사용량 추적
Claude Console에서 세션을 검사하고, 토큰 사용량과 정가 비용을 확인하며, 예상치 못한 에이전트 동작을 디버깅합니다.
Claude Console의 세션 뷰어를 사용하면 코드를 작성하지 않고도 세션에서 에이전트가 수행한 작업을 검사할 수 있습니다. 세션의 usage 합계를 사용하여 해당 작업이 소비한 양을 확인하세요.
Console에서 세션 검사하기
세션 뷰어는 Developer와 Admin만 접근할 수 있습니다. 세션 뷰어를 열려면 Console 사이드바로 이동하여 Managed Agents 아래의 Sessions를 선택하세요. 목록에는 워크스페이스의 모든 세션이 상태, 에이전트, 토큰 사용량, 비용, 생성 시간과 함께 표시됩니다. 세션을 선택하여 여세요.
세션 뷰어에는 다음이 표시됩니다:
- 타임라인 미니맵: 시간에 따른 세션 활동을 확대/축소하여 볼 수 있는 개요로, 멀티에이전트 세션에서는 스레드마다 하나의 레인이 있습니다. 레인을 선택하면 해당 스레드를 볼 수 있고, 마크를 선택하면 해당 이벤트로 이동합니다.
- 트랜스크립트: 모델 요청별로 그룹화된 대화로, 사고 과정, 입력 및 결과가 포함된 도구 호출, 스트리밍되는 메시지 텍스트를 포함합니다. 이벤트를 필터링하고 JSON으로 복사하거나 다운로드할 수 있습니다.
- 인스펙터: 세션에 대한 세부 정보를 다섯 개의 탭으로 보여주는 크기 조절 가능한 사이드 패널입니다.
| 인스펙터 탭 | 표시 내용 |
|---|---|
| Session | 세션의 세부 정보와 메타데이터, 시간에 따른 누적 비용, 그리고 세션 예산이 설정된 경우 예산 대비 지출입니다. |
| Events | 현재 스레드의 모든 원시 이벤트를 서버가 전송한 순서대로 보여줍니다. 이벤트를 선택하면 해당 JSON을 볼 수 있습니다. 페이지가 열려 있는 동안 스트리밍된 메시지에는 이벤트 델타를 보여주는 Deltas 뷰도 있습니다. |
| Tools | 세션의 에이전트에 구성된 도구와 함께 호출 횟수, 실패 횟수, 중앙값 소요 시간을 보여줍니다. 도구를 선택하면 해당 호출을 보고 트랜스크립트의 특정 호출로 이동할 수 있습니다. |
| Resources | 컨테이너 경로에 마운트된 파일, 리포지토리, 메모리 스토어를 보여주며, 각 스토어의 메모리와 이 세션이 해당 메모리에 적용한 변경 사항을 포함합니다. 또한 에이전트가 /mnt/session/outputs에 작성한 파일과 세션의 에이전트에 연결된 스킬도 나열합니다. |
| Threads | 모든 스레드를 상태, 컨텍스트 크기, 비용과 함께 보여줍니다. 스레드를 선택하면 에이전트, 모델, 컨텍스트 사용량, 비용 등의 세부 정보를 볼 수 있습니다. |
세션 URL에 ?event={event_id}를 추가하면 특정 이벤트에서 세션을 열 수 있습니다.
ant beta:sessions connect를 사용하면 ant CLI에서 동일한 뷰어를 열거나 터미널에서 세션을 실시간으로 확인할 수 있습니다. 자세한 내용은 터미널에서 Managed Agents 세션에 연결하기를 참조하세요.
사용량 추적
세션 객체에는 세션의 누적 사용량을 담은 usage 필드가 포함되어 있습니다. 여기에는 토큰 수, 서버 도구 사용, 활성 시간, 추적된 정가 비용이 포함됩니다. 세션이 유휴 상태가 된 후 세션을 가져오면 최신 합계를 읽을 수 있습니다.
{
"id": "sesn_01...",
"status": "idle",
"usage": {
"input_tokens": 5000,
"output_tokens": 3200,
"cache_read_input_tokens": 20000,
"cache_creation": {
"ephemeral_5m_input_tokens": 2000,
"ephemeral_1h_input_tokens": 0
},
"list_cost": {
"amount": "187",
"currency": "USD"
},
"active_seconds": 342.5,
"server_tool_use": {
"web_search_requests": 3,
"web_fetch_requests": 0
}
}
}| 필드 | 설명 |
|---|---|
input_tokens | 세션의 모든 모델 호출에 걸친 캐시되지 않은 입력 토큰입니다. |
output_tokens | 세션의 모든 모델 호출에 걸친 총 출력 토큰입니다. |
cache_read_input_tokens | 프롬프트 캐시에서 읽은 토큰입니다. |
cache_creation | 캐시 수명별로 분류된 캐시 생성 토큰입니다(ephemeral_5m_input_tokens 및 ephemeral_1h_input_tokens). |
list_cost | 공개 정가 요율로 책정된 세션의 누적 소비량으로, 문자열 형태의 센트 단위 정수와 통화 코드로 표시됩니다. |
active_seconds | 세션에서 하나 이상의 스레드가 실행 중이었던 누적 시간입니다. 동시 스레드의 겹치는 활동은 한 번만 계산됩니다. 세션의 런타임 비용은 이 시간을 기준으로 책정됩니다. |
server_tool_use | 가격 책정을 위한 서버 실행 도구 요청 횟수입니다. 웹 검색 요청은 요청당 정가 비용에 반영됩니다. 웹 가져오기 요청은 요청당 요금이 없고 측정되지 않으므로 web_fetch_requests는 0으로 표시됩니다. |
캐시 항목은 기본적으로 5분 TTL을 사용하므로, 해당 시간 내에 연속으로 이어지는 턴은 캐시 읽기의 이점을 얻어 토큰당 비용이 줄어듭니다.
세션의 stats 객체에는 자체 active_seconds가 있으며, 이는 겹치는 활동을 한 번만 계산하는 대신 각 스레드의 자체 활성 시간을 합산합니다.
스레드별 사용량
각 세션 스레드의 자체 usage에도 list_cost와 active_seconds가 포함됩니다. 스레드별 수치는 독립적으로 반올림되며 세션의 실행 시간 비용을 제외하므로, 합계가 세션의 list_cost와 정확히 일치하지 않습니다. 세션 수치가 기준이 되는 값입니다.
스트림에서 사용량 읽기
이러한 합계를 확인하기 위해 세션을 폴링할 필요는 없습니다. session.usage 이벤트는 세션 스트림과 이벤트 기록에서 동일한 누적 스냅샷을 전달합니다. 스냅샷에는 usage 객체와 세션의 budget이 포함되며, 세션에 예산이 없으면 budget은 null입니다.
이 이벤트는 타이머가 아닌 유휴 상태 전환 시에 발생합니다:
- 세션은 중지 사유와 관계없이 유휴 상태가 되기 직전에 이벤트를 하나 발생시킵니다.
- 세션은 스레드가 세션 예산에 도달하여 일시 중지될 때 이벤트를 하나 발생시킵니다.
지출 한도 적용
지출 한도를 적용하려면 사용량을 폴링하고 직접 세션을 중지하는 대신 세션 예산을 설정하세요. 플랫폼은 세션의 소비량을 지속적으로 가격 책정하며, 정가 비용이 상한에 도달하면 각 스레드를 다음 모델 요청 전에 일시 중지합니다. 스트림에서 이것이 어떻게 나타나는지는 세션이 예산에 도달할 때를 참조하세요.
디버깅 팁
- 세션 이벤트 확인: 세션은
session.error이벤트를 통해 오류를 보고합니다. - 도구 결과 검토: 도구 실행 실패는 예상치 못한 에이전트 동작의 원인을 설명하는 경우가 많습니다. 인스펙터의 Tools 탭에서 각 도구의 실패를 확인할 수 있습니다.
- 시스템 프롬프트 활용: 시스템 프롬프트에 로깅 지침을 추가하여 에이전트가 수행한 작업과 발견한 내용을 요약하도록 하세요.
- 미리보기 문제 해결: 이벤트 델타를 사용하도록 설정한 스트림이 예상대로 동작하지 않으면 미리보기 문제 해결을 참조하세요.
다음 단계
이벤트를 전송하고, 응답을 스트리밍하며, 실행 중인 세션을 중단하거나 방향을 전환합니다.
공개 정가 요율로 적용되는 엄격한 달러 예산으로 세션의 지출을 제한합니다.
Was this page helpful?