이 페이지는 사용 추적 시스템 테이블을 사용하여 Unity Gateway 서비스 사용을 모니터링하는 방법을 설명합니다.
사용 추적 테이블은 모델 서비스, 모델 제공자 서비스, MCP 서비스의 요청 및 응답 세부 정보를 담고 있습니다. 모델 요청의 경우, 토큰 사용과 지연 시간과 같은 지표를 기록합니다. MCP 요청의 경우, 통화 및 서비스 메타데이터를 기록합니다. 테이블을 사용해 사용자 모니터링, 비용 추적, 서비스 사용 및 성능 분석에 활용하세요.
사용량 추적은 ai_query Databricks에서 제공하는 모델 서비스에 대한 요청도 캡처합니다.
계정 및 작업 영역 관리자는 거버넌스 허브의 AI 페이지에서 AI 사용량에 대한 통합된 개요를 볼 수 있습니다.
Requirements
- Unity Gateway 지원 지역 내 Azure Databricks 작업 공간.
- 작업 영역에서 Unity 카탈로그가 사용하도록 설정되었습니다. Unity 카탈로그에 작업 영역 사용을 참조하세요.
Pricing
사용 추적은 청구된 Unity Gateway 기능입니다. Azure Databricks는 테이블에 system.ai_gateway.usage 기록한 사용량에 대해 요금을 부과합니다.
Unity Gateway 가격 책정을 참고하세요.
사용 현황 테이블 쿼리
Unity Gateway는 사용 데이터를 시스템 테이블에 system.ai_gateway.usage 기록합니다. UI에서 테이블을 보거나 Databricks SQL 또는 Notebook에서 테이블을 쿼리할 수 있습니다.
참고
기본적으로 테이블을 system.ai_gateway.usage 보거나 쿼리하려면 계정 및 메타스토어 관리자 역할이 모두 필요합니다. 관리자는 사용자, 그룹, 서비스 주체의 권한을 제어하기 위해 시스템 테이블에 대한 접근 권한을 관리할 수 있습니다.
UI에서 테이블을 보려면 모델 서비스 페이지에서 사용량 추적 테이블 링크를 클릭하여 카탈로그 탐색기에서 테이블을 엽니다.
Databricks SQL 또는 Notebook에서 테이블을 쿼리하려면 다음을 수행합니다.
SELECT * FROM system.ai_gateway.usage;
Tip
지니 코드 (에이전트 모드)는 이 작업을 수행할 수 있습니다. 다음 예제 프롬프트를 사용해 보세요.
Query the system.ai_gateway.usage table to analyze AI Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.
기본 제공 사용 대시보드
참고
일부 작업 영역에는 아직 Govern 드롭다운이 표시되지 않습니다. 해당 작업 공간에서는 Unity 게이트웨이 페이지의 독립형 대시보드 만들기, 대시보드 보기, 업데이트 버튼을 사용하세요.
내장 사용 대시보드 만들기
계정 관리자는 내장 Unity Gateway 사용 대시보드를 만들어 사용량을 모니터링하고 비용을 추적하며 모델 서비스 성능과 사용량에 대한 인사이트를 얻을 수 있습니다. Unity Gateway 페이지에서 오른쪽 상단의 Govern 을 클릭한 후 Create Usage Dashboard를 클릭하세요. 대시보드 쿼리를 실행하는 웨어하우스가 자동으로 선택됩니다.
참고
대시보드 생성은 SELECT 테이블에 대한 system.ai_gateway.usage 권한이 필요하므로 계정 관리자에게만 제한됩니다. 대시보드의 데이터는 usage 테이블의 보존 정책을 준수합니다.
어떤 시스템 테이블을 사용할 수 있는지 확인하세요..
내장 사용 대시보드의 최신 버전이 제공되면, 계정 관리자는 Unity Gateway 페이지의 Govern 드롭다운에서 대시보드 버전 행에서 Update를 클릭할 수 있습니다.
다음 대시보드 구성 옵션을 사용하여 대시보드를 관리할 수 있습니다.
- 범위: 대시보드의 범위를 계정 또는 작업 영역으로 지정할지 여부를 선택합니다.
- 사용 권한: 대시보드 소유자의 사용 권한을 사용하여 쿼리를 실행할지 또는 각 뷰어의 권한을 사용하여 쿼리를 실행할지 선택합니다. 공유 데이터 사용 권한이란?을 참조하세요.
- 자동 업데이트: 이 옵션을 활성화하면 최신 버전이 나올 때마다 대시보드가 자동으로 업데이트되고 계정 관리자가 Unity Gateway 페이지를 방문합니다.
대시보드가 버전 0.3 이상으로 업데이트되면 6시간마다 대시보드를 새로 고치도록 일정이 자동으로 생성됩니다. 필요한 경우 Lakeview 대시보드에서 이 일정을 사용하지 않도록 설정할 수 있습니다.
일정 만들기를 참조하세요.
사용량 대시보드 보기
대시보드를 보려면 Unity Gateway 페이지 오른쪽 상단의 Govern 을 클릭한 후 Usage Dashboard를 클릭하세요. 대시보드는 새 탭에서 열립니다. 내장 대시보드는 Unity Gateway 모델 서비스 사용, 성능, 비용을 포괄적으로 확인할 수 있습니다. 여기에는 여러 페이지 추적 요청, 토큰 사용량, 대기 시간 메트릭, 오류 비율, 비용 분석, 외부 MCP 서버 트래픽 및 코딩 에이전트 작업이 포함됩니다.
대시보드는 기본적으로 작업 영역 간 분석을 제공합니다. 모든 대시보드 페이지는 날짜 범위 및 작업 영역 ID를 기준으로 필터링할 수 있습니다.
- 개요 탭: 일일 요청 볼륨, 시간에 따른 토큰 사용량 추세, 토큰 사용량별 상위 사용자 수 및 총 고유 사용자 수를 포함한 상위 수준 사용 메트릭을 표시합니다. 이 탭을 사용하여 전체 Unity Gateway 활동의 빠른 스냅샷을 확인하고 가장 활발한 사용자와 모델을 식별하세요.
- 성능 탭: 대기 시간 백분위수(P50, P90, P95, P99), 시간-첫 번째 바이트, 오류 비율 및 HTTP 상태 코드 배포를 포함한 주요 성능 메트릭을 추적합니다. 이 탭을 사용하여 모델 서비스 상태를 모니터링하고 성능 병목 상태 또는 안정성 문제를 식별합니다.
- 사용 탭: 모델 서비스, 작업 영역 및 요청자별 자세한 사용량 분석을 표시합니다. 이 탭에는 토큰 사용 패턴, 요청 배포 및 캐시 적중 비율이 표시됩니다.
- 비용 관찰 탭: 모델 서비스, 대상 모델, 사용자, 서비스 태그 및 요청 태그별 비용 분석을 표시합니다. 이 탭에는 외부 모델에 대한 예상 비용도 포함됩니다. Unity 게이트웨이 비용 분석(Analyze Unity Gateway Cost)을 참조하세요.
- 외부 MCP 서버 탭: 외부 MCP 서버 트래픽에 대한 요청 볼륨, 오류율, 사용자 및 연결 및 일일 사용 추세를 표시합니다.
- 코딩 에이전트 탭: Claude Code, Codex CLI, Cursor, Gemini CLI 등 통합 코딩 에이전트의 활동을 추적합니다. 이 탭은 개발자 도구 사용을 모니터링하기 위해 추가되거나 제거된 코드 줄, 코딩 세션, 커밋 및 활성 날짜와 같은 메트릭을 보여 줍니다. 자세한 내용은 코딩 에이전트 대시보드 를 참조하세요.
사용량 테이블 스키마
테이블에 system.ai_gateway.usage 는 다음 스키마가 있습니다.
| 열 이름 | Type | 설명 | Example |
|---|---|---|---|
account_id |
STRING | 계정 ID입니다. | 11d77e21-5e05-4196-af72-423257f74974 |
workspace_id |
STRING | 작업 영역 ID입니다. | 1653573648247579 |
request_id |
STRING | 요청의 고유 식별자 | b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00 |
invocation_id |
STRING | 각 개별 유추 호출에 대한 고유 식별자입니다. 여러 호출은 가드레일 검사나 멀티턴 에이전트 호출과 같이 동일한 request_id를 공유할 수 있습니다. 구분하는 데 invocation_id를 사용하세요. |
c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60 |
schema_version |
정수 | 사용 레코드의 스키마 버전입니다. | 1 |
service_type |
STRING | 사용 기록을 생성한 서비스 유형. 값은 MODEL_SERVICE, MCP_SERVICE, 그리고 MODEL_PROVIDER_SERVICE입니다. |
MODEL_SERVICE |
service_id |
STRING | 모델 서비스, MCP 서비스 또는 모델 제공자 서비스의 ID. | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
service_name |
STRING | Unity 카탈로그에는 서비스 명칭이 완전히 정식 명시되어 있습니다. | main.default.github_tools |
service_tags |
MAP | Unity 카탈로그에 적용된 자원 태그는 생성 또는 업데이트 시 보안 가능합니다. 이 요청들은 서비스에 대한 모든 요청에 적용되며, 팀, 비용 센터, 프로젝트별로 사용량을 분류하는 데 유용합니다. | {"team": "engineering"} |
endpoint_id |
STRING | Unity Gateway 모델 서비스의 고유 ID. | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
endpoint_name |
STRING | Unity Gateway 모델 서비스의 이름입니다. | system.ai.gpt-5-2 |
endpoint_tags |
MAP | 모델 서비스를 만들거나 업데이트할 때 구성된 태그입니다. 모델 서비스에 대한 모든 요청에 적용되며 팀, 비용 센터 또는 프로젝트별로 서비스를 분류하는 데 유용합니다. | {"team": "engineering"} |
endpoint_metadata |
구조 |
creator, creation_time, last_updated_time, destinations, inference_table 및 fallbacks를 포함한 모델 서비스 메타데이터. |
{"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...} |
event_time |
TIMESTAMP | 요청을 받은 타임스탬프입니다. | 2026-01-20T19:48:08.000+00:00 |
latency_ms |
LONG | 총 대기 시간(밀리초)입니다. | 300 |
time_to_first_byte_ms |
LONG | 첫 번째 바이트 시간(밀리초)입니다. | 300 |
destination_type |
STRING | 대상 유형(예: 외부 모델 또는 기본 모델)입니다. | PAY_PER_TOKEN_FOUNDATION_MODEL |
destination_name |
STRING | 대상 모델 또는 공급자의 이름입니다. | system.ai.gpt-5-2 |
destination_id |
STRING | 대상의 고유 ID입니다. | 507e7456151b3cc89e05ff48161efb87 |
destination_model |
STRING | 요청에 사용되는 특정 모델입니다. | GPT-5.2 |
requester |
STRING | 요청을 수행한 사용자 또는 서비스 주체의 ID입니다. | user.name@email.com |
requester_type |
STRING | 요청자 유형(사용자, 서비스 주체 또는 사용자 그룹)입니다. | USER |
ip_address |
STRING | 요청자의 IP 주소입니다. | 1.2.3.4 |
url |
STRING | 요청의 URL입니다. | https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions |
user_agent |
STRING | 요청자의 사용자 에이전트입니다. | OpenAI/Python 2.13.0 |
api_type |
STRING | API 호출 유형(예: 채팅, 완료 또는 포함)입니다. | mlflow/v1/chat/completions |
request_tags |
MAP | HTTP 헤더를 사용하여 Databricks-Ai-Gateway-Request-Tags 개별 요청과 함께 전송된 사용자 제공 태그입니다. 요청 태그를 사용하여 특정 프로젝트, 팀, 환경 또는 최종 사용자에 대한 사용량을 특성화합니다. 사용 추적과 요청 태깅에 관한 태그 요청을 참조하세요. |
{"project": "chatbot", "team": "ml-platform"} |
invocation_metadata |
구조 | 요청이 어디서 시작되었는지, 모델 제공자가 보고한 서비스 계층, 그리고 요청이 Claude 구독을 사용했는지에 대한 정보입니다. | {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false} |
input_tokens |
LONG | 입력 토큰의 수입니다. | 100 |
output_tokens |
LONG | 출력 토큰의 수입니다. | 100 |
total_tokens |
LONG | 총 토큰 수(입력 + 출력)입니다. | 200 |
token_details |
구조 |
cache_creation_5m_input_tokens, output_reasoning_tokens, cache_creation_1h_input_tokens, file_search_count, num_web_search_queries, cache_read_input_tokens, cache_creation_input_tokens를 포함한 토큰 및 도구 사용 상세 내역 |
{"cache_read_input_tokens": 100, ...} |
response_content_type |
STRING | 응답의 콘텐츠 형식입니다. | application/json |
status_code |
INT | 응답의 HTTP 상태 코드입니다. | 200 |
routing_information |
구조 |
폴백 시도에 대한 라우팅 세부 정보입니다.
attempts 배열에는 요청 중 시도된 각 모델에 대해 priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time, 및 end_time가 포함됩니다. |
{"attempts": [{"priority": "1", ...}]} |
mcp_metadata |
구조 | MCP 서비스에 대한 요청의 세부 사항, 호출된 도구, 서버 유형, JSON-RPC 작업 등이 포함됩니다.
MCP_SERVICE개 행에 대해 채워집니다. |
{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"} |
session_metadata |
구조 | 세션 및 클라이언트 맥락, 세션 및 서브에이전트 ID, 코딩 에이전트 이름과 버전, 클라이언트 인터페이스, 추론 노력, 스마트 라우팅 레시피 등이 포함됩니다. 이 필드들을 사용해 관련 요청을 그룹화하고 에이전트 또는 세션별 사용량을 분석하세요. | {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...} |
auth_mode |
STRING | 요청을 인증하는 데 사용되는 Databricks 자격 증명 유형: 개인 액세스 토큰(PAT) 또는 OAuth 토큰(OAUTH). |
OAUTH |
중첩된 열 스키마
다음 표들은 중첩된 STRUCT 열 내의 필드를 설명합니다. 현장 가용성은 요청에 사용되는 서비스, 모델, 클라이언트에 따라 달라집니다.
호출 및 토큰 메타데이터
| 필드 경로 | Type | 설명 |
|---|---|---|
invocation_metadata.source |
STRING | 요청을 시작한 애플리케이션, 서비스 또는 API 중 하나. 이 필드를 사용해 사용 정보를 출처에 귀속하세요. 값에는 EXTERNAL_CLIENT, AI_QUERY, GUARDRAIL, MANAGED_AGENT, AI_PLAYGROUND가 포함됩니다. |
invocation_metadata.service_tier |
STRING | 추론 응답에서 모델 제공자가 보고하는 서비스 계층, 예를 들어 defaultpriority또는 . 이 필드를 사용하여 제공자 가격 계층 간 사용량을 비교하세요. |
invocation_metadata.relayed |
BOOLEAN | 요청이 발신자의 Claude 구독을 통해 Anthropic에 전달되었는지. |
token_details.cache_read_input_tokens |
LONG | 프롬프트 캐시에서 읽히는 토큰 수입니다. |
token_details.cache_creation_input_tokens |
LONG | 프롬프트 캐시에 기록된 토큰 수. |
token_details.output_reasoning_tokens |
LONG | 출력에 포함된 추론 토큰의 수. |
token_details.cache_creation_5m_input_tokens |
LONG | 5분 수명으로 프롬프트 캐시에 기록된 입력 토큰 수. |
token_details.cache_creation_1h_input_tokens |
LONG | 프롬프트 캐시에 기록된 입력 토큰의 수로, 수명은 1시간입니다. |
token_details.file_search_count |
LONG | 요청의 일부로 이루어진 파일 검색 도구 호출 횟수. |
token_details.num_web_search_queries |
LONG | 요청에 포함된 청구 가능한 웹 검색 쿼리 수. |
MCP 서비스 메타데이터
이 필드들은 mcp_metadata개 행에 대해 MCP_SERVICE에 채워집니다.
| 필드 경로 | Type | 설명 |
|---|---|---|
mcp_metadata.tool_name |
STRING | MCP tools/call 요청에 의해 호출된 도구의 이름입니다. 이 필드를 이용해 서버에서 개별 도구의 사용 현황을 분석하세요. |
mcp_metadata.server_type |
STRING | 요청을 처리하는 MCP 서버의 범주, 예를 들어 EXTERNALSYSTEM또는 . |
mcp_metadata.json_rpc_method |
STRING | 클라이언트가 요청한 JSON-RPC 작업, 예를 들어 tools/call 도구 호출, tools/list 도구 탐색, initialize 세션 시작 등이 포함됩니다. |
세션 메타데이터
이 필드들은 session_metadata 세션 내 요청을 상관시키고 코딩 에이전트, 클라이언트 인터페이스, 요청 설정을 구분하는 데 도움을 줍니다. 각 필드는 클라이언트나 요청에서 해당 정보가 제공될 때 채워집니다.
| 필드 경로 | Type | 설명 |
|---|---|---|
session_metadata.client_session_id |
STRING | 클라이언트가 제공한 세션 ID. 같은 대화나 코딩 에이전트 세션 중에 요청된 것을 그룹화하는 데 사용하세요. |
session_metadata.client_subagent_id |
STRING | 클라이언트가 제공한 하위 에이전트 ID입니다. 이 기능을 client_session_id 사용하여 상위 세션 내에서 서브에이전트의 요청을 구분하세요. |
session_metadata.coding_agent |
STRING | 요청을 보낸 코딩 에이전트의 정규화된 이름, 예를 들어 claude-codecodex또는 . |
session_metadata.agent_version |
STRING | 코딩 에이전트가 보고한 버전입니다.
coding_agent와 함께 사용해 에이전트 릴리스 간 사용량을 비교하세요. |
session_metadata.surface |
STRING | 코딩 에이전트가 요청을 보내는 클라이언트 인터페이스로, 명령줄 인터페이스, IDE, 데스크톱 애플리케이션 등이 포함됩니다. |
session_metadata.reasoning_effort |
STRING | 요청에 명시된 추론 노력, 예를 들어 low, medium, 또는 high. 사용 가능한 값은 모델과 API에 따라 다릅니다. |
session_metadata.smart_router_name |
STRING | 고객이 선택한 스마트 라우팅 레시피의 이름입니다. 사용량을 라우팅 레시피별로 그룹화하는 데 사용하세요. |
사용량 추적에 대한 태그 요청
요청 태그는 호출자가 개별 요청에 연결하는 사용자 지정 키-값 쌍입니다. 요청 태그를 사용하여 프로젝트, 팀, 환경, 최종 사용자 또는 조직과 관련된 다른 차원별 사용량을 특성화합니다. 요청 태그는 테이블에 기록 system.ai_gateway.usage 되며 사용량 현황 데이터를 필터링, 집계 및 분석하는 데 사용할 수 있습니다.
개별 요청에 태그를 지정하려면 문자열 값에 Databricks-Ai-Gateway-Request-Tags 문자열 키를 매핑하는 JSON 개체가 있는 HTTP 헤더를 포함합니다. 요청 태그는 사용 현황 request_tags 테이블 및 유추 테이블의 열에 기록됩니다.
REST API, OpenAI SDK, Anthropic SDK로 요청 태그를 설정하는 예시는 요청 태깅을 참조하세요.
예를 들어 요청 태그를 사용하여 프로젝트별로 사용량을 집계할 수 있습니다.
SELECT
request_tags['project'] AS project,
COUNT(*) AS request_count,
SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE request_tags['project'] IS NOT NULL
GROUP BY request_tags['project']
ORDER BY total_tokens DESC;
Limitations
- Unity Gateway는 1 MiB를 초과하는 비스트리밍, 비임베딩 응답에 대해 토큰 사용을 추적하지 않습니다.