콘텐츠로 이동

AgentMeter 사용 가이드

AgentMeter는 로컬 코딩 Agent의 계정, 할당량, Token 사용 현황을 확인하는 데스크톱용 Agent 사용량 도구입니다. AgentMeter를 Guance에 연결하면 사용량 메트릭과 Agent 실행 트레이스를 현재 워크스페이스에 보고하여 Agent의 사용량, 성능, 호출 과정을 통합 분석할 수 있습니다.

AgentMeter는 현재 Codex, Claude Code, WorkBuddy를 지원합니다. Agent별로 제공되는 데이터가 다릅니다:

Agent 지원 OS 로컬 표시 서비스 연동
Codex macOS, Windows, Linux 계정 및 요금제, 할당량 창, Token 이력, 사용 가능한 Credits 기본 수집 및 확장 수집 지원
Claude Code macOS, Windows, Linux 로컬 Token 이력. 현재 계정에서 공식 할당량 필드를 제공하는 경우 구독 할당량도 표시 기본 수집 및 확장 수집 지원
WorkBuddy macOS, Windows 계정 및 요금제, 잔여 Credit 기본 수집 및 확장 수집 지원
데이터 산정 기준 안내
  • Codex Token은 현재 로그인한 계정의 사용량 데이터에서 가져옵니다.
  • Claude Code Token은 로컬 통계 캐시와 세션 기록을 집계한 값으로, 현재 디바이스에서 확인할 수 있는 사용량만 나타냅니다.
  • WorkBuddy는 현재 Token 이력과 롤링 할당량 창을 제공하지 않으며, AgentMeter는 누락된 데이터를 0으로 대체하지 않습니다.
  • Agent 또는 계정에서 반환되지 않은 필드는 표시하지 않으며 추정값도 보완하지 않습니다.

AgentMeter 설치

설치 전에 먼저 현재 디바이스에 확인하려는 Agent를 설치하고 로그인하세요. 운영체제와 프로세서 아키텍처에 맞는 설치 패키지를 다운로드하세요:

운영체제 아키텍처 설치 패키지
macOS Apple 칩 DMG 다운로드
macOS Intel 칩 DMG 다운로드
Windows ARM64 ZIP 다운로드
Windows x86-64 ZIP 다운로드
Debian / Ubuntu ARM64 DEB 다운로드
Debian / Ubuntu x86-64 DEB 다운로드
Fedora / RHEL ARM64 RPM 다운로드
Fedora / RHEL x86-64 RPM 다운로드

macOS

  1. 다운로드한 DMG 파일을 엽니다.
  2. AgentMeter를 Applications(응용 프로그램)으로 드래그합니다.
  3. 응용 프로그램 디렉터리에서 AgentMeter를 실행합니다.

AgentMeter는 실행 후 메뉴 바에 상주하며 Dock 아이콘은 표시되지 않습니다.

Windows

  1. 다운로드한 ZIP 파일의 압축을 풉니다.
  2. 압축을 푼 설치 프로그램을 실행합니다.
  3. 설치가 완료되면 AgentMeter를 실행합니다.

AgentMeter는 실행 후 시스템 트레이에 상주합니다.

Linux

Debian 또는 Ubuntu에서는 다음 명령으로 DEB 패키지를 설치합니다:

sudo apt install ./AgentMeter-latest-linux-<架构>.deb

Fedora 또는 RHEL에서는 다음 명령으로 RPM 패키지를 설치합니다:

sudo dnf install ./AgentMeter-latest-linux-<架构>.rpm

<架构>를 arm64 또는 amd64로 바꿉니다. 설치가 완료되면 앱 목록에서 AgentMeter를 실행합니다.

Agent 사용량 확인

AgentMeter를 실행한 후 메뉴 바 또는 시스템 트레이의 AgentMeter 아이콘을 클릭하여 플로팅 패널을 엽니다. AgentMeter는 현재 디바이스에 설치된 Agent를 자동으로 감지하고 읽을 수 있는 사용량 정보를 표시합니다.

  • 새로고침을 클릭하면 계정, 할당량, 사용량 데이터가 즉시 업데이트됩니다.
  • Token 메트릭을 클릭하면 일별, 월별 달력 또는 추세 그래프로 표시된 이력 사용량을 확인할 수 있습니다.
  • 설정 > Agents로 이동하여 플로팅 패널 또는 시스템 바에 표시할 Agent를 선택하고 드래그하여 표시 순서를 조정합니다.
  • 설정 > 일반으로 이동하여 언어, 외관, 부팅 시 자동 실행을 구성합니다.
  • 설정 > 정보로 이동하여 AgentMeter 업데이트를 확인하고 설치합니다.

Claude Code를 처음 연결하여 할당량을 읽은 후에는 Claude Code 세션을 한 번 열거나 재시작해야 합니다. 현재 계정 또는 Claude Code 버전에서 구독 할당량 필드를 반환하지 않더라도 AgentMeter는 로컬 Token 이력을 계속 표시할 수 있습니다.

Guance 연동

Agent 데이터를 Guance에 보고하려면 설정 > 서비스 연동으로 이동합니다. 서비스 연동에는 다음 두 가지 수집 단계가 있습니다:

수집 단계 수집 내용 데이터 용도
기본 수집 계정, 요금제, Token, 할당량, Credit 등 스냅샷 메트릭 개인 또는 Agent의 사용량과 할당량 상태 분석
확장 수집 Session, Trace, 모델 호출, Tool, Skill 등 실행 데이터 Agent 모니터링에서 전체 호출 트레이스, 성능, 행동 위험 분석

기본 수집은 AgentMeter에 내장되어 있으며, 확장 수집은 AgentMeter가 obs-agent-connector를 관리합니다. 두 수집 방식은 Agent별로 각각 활성화할 수 있습니다.

1단계: 연결 구성

Agent 모니터링 > 요약 > Agent 연동으로 이동하여 연동 구성 페이지에서 현재 워크스페이스의 Data Endpoint와 X-Token을 확인합니다. 그런 다음 설정 > 서비스 연동 > 연결 구성에서 JSON 구성 파일을 가져오거나 다음 정보를 직접 입력합니다:

구성 항목 필수 여부 설명
Data Endpoint 예 현재 사이트의 데이터 수신 주소. HTTP 또는 HTTPS 기본 주소만 입력
X-Token 예 현재 워크스페이스의 데이터 보고 Token
User ID 예 사용자 고유 식별자. User별 집계, 필터링, 드릴다운에 사용
User Name 예 사용자 표시 이름. 표시 및 검색에 사용

가져오기 파일은 다음 형식을 사용합니다:

{
  "schemaVersion": 1,
  "ingestEndpoint": "<Data Endpoint>",
  "xToken": "<X-Token>",
  "user_id": "<User ID>",
  "user_name": "<User Name>"
}

구성 파일은 .json 확장자를 사용해야 하며 크기는 64KB를 초과할 수 없습니다. 저장 후 AgentMeter는 X-Token을 숨기며 인터페이스에 전체 값을 표시하지 않습니다.

2단계: 기본 수집 활성화

기본 수집 영역에서 사용량 메트릭을 보고할 Agent의 스위치를 켭니다. 활성화하면 AgentMeter가 즉시 데이터를 한 번 보고하며, 이후 60초마다 최신 스냅샷을 보고합니다.

기본 수집 데이터는 agent_runtime 메저먼트에 기록되며, AgentMeter 메트릭 필드는 agent_meter_로 시작합니다. 기본 수집에는 사용량과 계정 스냅샷만 포함되며 Session 또는 Trace 데이터가 생성되지 않습니다.

3단계: 확장 수집 활성화

  1. 확장 수집 영역에서 커넥터 설치를 클릭합니다.
  2. 설치가 완료되면 실행 트레이스를 수집할 Agent에 대해 확장 수집을 활성화합니다.
  3. 페이지 안내에 따라 구성과 검증을 완료합니다.
  4. 실행 중인 Agent 세션을 재시작하여 수집 구성을 적용합니다.
  5. Agent로 새 세션 또는 새 작업을 시작합니다.

AgentMeter는 현재 디바이스에서 감지되고 지원되는 Agent만 관리합니다. 커넥터를 설치한 후에도 서비스 연동 페이지에서 Agent별로 통합을 개별 활성화, 비활성화, 검증 또는 제거할 수 있습니다.

데이터 검증

서비스 연동을 완료한 후 수집 단계별로 데이터를 검증할 수 있습니다:

  • 기본 수집: 메트릭 분석에서 agent_runtime 메저먼트를 선택하고 agent_meter_로 시작하는 메트릭 필드를 조회합니다.
  • 확장 수집: Agent 모니터링 > 탐색기로 이동하여 Agent 유형, User, Session 또는 Trace별로 데이터를 확인합니다.
  • 추세 분석: Agent 모니터링 > 분석 대시보드로 이동하여 Agent 유형, Agent ID 또는 Agent 이름으로 데이터를 필터링합니다.

확장 수집을 방금 활성화한 경우 Agent로 새 작업을 한 번 완료한 후 조회하세요. 수집 구성은 활성화 이전의 전체 Trace 데이터를 소급하여 전송하지 않습니다.

장기 작업 알림 구성

AgentMeter는 Codex 장기 작업이 완료되면 Lark 그룹 봇을 통해 알림을 전송할 수 있습니다.

  1. 설정 > 알림으로 이동합니다.
  2. 알림과 장기 작업 완료 알림을 활성화합니다.
  3. Lark 그룹 봇의 Webhook 주소를 입력합니다.
  4. 봇에서 서명 검증을 사용하는 경우 서명 키도 함께 입력합니다.
  5. 장기 작업 임계값을 설정하고 저장합니다.
  6. 테스트 알림을 클릭하여 그룹 채팅에서 메시지를 정상적으로 수신하는지 확인합니다.

실행 시간이 임계값에 도달한 Codex 작업에만 완료 알림이 전송됩니다.

자주 묻는 질문

Agent가 감지되지 않음

Agent가 설치되어 있고 최소 한 번 이상 정상적으로 실행되었는지 확인한 후 설정 > Agents에서 새로고침을 클릭합니다. Codex는 계정 로그인도 완료해야 합니다. Linux는 현재 WorkBuddy Desktop 감지를 지원하지 않습니다.

Claude Code에 할당량 데이터가 없음

Claude Code 세션을 한 번 열거나 재시작하여 AgentMeter가 첫 번째 할당량 응답을 받을 때까지 기다립니다. 일부 계정 요금제 또는 Claude Code 버전에서는 할당량 필드를 제공하지 않으며, 이 경우에도 Token 이력은 계속 사용할 수 있습니다.

기본 수집에 데이터가 없음

연결 구성이 저장되었는지, 대상 Agent의 기본 수집 스위치가 켜져 있는지 확인하고 최소 한 번의 보고 주기를 기다립니다. 그런 다음 기본 수집 진단 보기를 클릭하여 최근 수집 시간, 보고 시간, 오류 정보를 확인합니다.

확장 수집에 Trace가 없음

커넥터가 설치되었는지, 대상 Agent의 확장 수집 스위치가 켜져 있고 검증을 통과했는지 확인합니다. Agent를 재시작한 후 새 작업을 시작하고 Agent 모니터링 탐색기에서 조회합니다. 그래도 데이터가 없으면 진단 정보 보기를 클릭하여 커넥터 상태를 확인합니다.

진단 로그 확인

AgentMeter 진단 로그에는 작업 내용, 전체 Token, Webhook 또는 서명 키가 기록되지 않습니다. 기본 로그 경로는 다음과 같습니다:

운영체제 로그 경로
macOS ~/Library/Logs/AgentMeter/agentmeter.log
Windows %LOCALAPPDATA%\\AgentMeter\\Logs\\agentmeter.log
Linux ${XDG_STATE_HOME:-~/.local/state}/agentmeter/agentmeter.log

이전 로그는 .1부터 .4까지의 접미사를 사용합니다. 문제를 제출할 때에는 AgentMeter 버전, 운영체제, Agent 유형, 비식별화된 진단 로그를 함께 제공하는 것이 좋습니다.

추가 자료

문서 평가

이 페이지가 도움이 되었나요?