Important
이 기능은 베타 버전으로 제공됩니다. 계정 관리자는 계정 콘솔 미리 보기 페이지에서 이 기능에 대한 액세스를 제어할 수 있습니다. Azure Databricks 미리 보기 관리를 참조하세요.
이 페이지에서는 사용량 추적 시스템 테이블을 사용하여 Unity AI Gateway 서비스의 사용량을 모니터링하는 방법을 설명합니다.
사용량 추적 테이블은 모델 서비스에 대한 요청 및 응답 세부 정보를 자동으로 캡처하여 토큰 사용량 및 대기 시간과 같은 필수 메트릭을 로깅합니다. 이 테이블의 데이터를 사용하여 사용자를 모니터링하고, 비용을 추적하고, 모델 서비스 성능 및 소비에 대한 인사이트를 얻을 수 있습니다.
사용량 추적은 ai_query Databricks에서 제공하는 모델 서비스에 대한 요청도 캡처합니다.
Requirements
- 계정에 대해 Unity AI Gateway 미리 보기가 사용하도록 설정되었습니다. Azure Databricks 미리 보기 관리를 참조하세요.
- Azure Databricks 작업 영역은 유니티 AI 게이트웨이 지원 지역.
- 작업 영역에서 Unity 카탈로그가 사용하도록 설정되었습니다. Unity 카탈로그에 작업 영역 사용을 참조하세요.
사용 현황 테이블 쿼리
Unity AI 게이트웨이는 사용량 현황 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.
기본 제공 사용 대시보드
기본 제공 사용 대시보드 만들기
계정 관리자는 AI 게이트웨이 페이지에서 대시보드 만들기 를 클릭하여 기본 제공 Unity AI Gateway 사용량 대시보드를 만들어 사용량을 모니터링하고, 비용을 추적하고, 모델 서비스 성능 및 소비에 대한 인사이트를 얻을 수 있습니다. 계정 관리자는 모든 후속 쿼리에 적용되는 대시보드 쿼리를 실행하는 데 사용되는 웨어하우스를 업데이트할 수도 있습니다.
참고
대시보드 생성은 SELECT 테이블에 대한 system.ai_gateway.usage 권한이 필요하므로 계정 관리자에게만 제한됩니다. 대시보드의 데이터는 usage 테이블의 보존 정책을 준수합니다.
어떤 시스템 테이블을 사용할 수 있는지 확인하세요..
최신 버전의 기본 제공 사용 대시보드를 사용할 수 있는 경우 계정 관리자는 AI 게이트웨이 페이지의 대시보드 작업 메뉴에서 업데이트를 클릭할 수 있습니다.
다음 대시보드 구성 옵션을 사용하여 대시보드를 관리할 수 있습니다.
- 범위: 대시보드의 범위를 계정 또는 작업 영역으로 지정할지 여부를 선택합니다.
- 사용 권한: 대시보드 소유자의 사용 권한을 사용하여 쿼리를 실행할지 또는 각 뷰어의 권한을 사용하여 쿼리를 실행할지 선택합니다. 공유 데이터 사용 권한이란?을 참조하세요.
- 자동 업데이트: 이 옵션을 사용하도록 설정하면 최신 버전을 사용할 수 있게 되고 계정 관리자가 AI 게이트웨이 페이지를 방문할 때마다 대시보드가 자동으로 업데이트됩니다.
대시보드가 버전 0.3 이상으로 업데이트되면 6시간마다 대시보드를 새로 고치도록 일정이 자동으로 생성됩니다. 필요한 경우 Lakeview 대시보드에서 이 일정을 사용하지 않도록 설정할 수 있습니다.
일정 만들기를 참조하세요.
사용량 대시보드 보기
대시보드를 보려면 AI 게이트웨이 페이지에서 대시보드 보기를 클릭합니다. 기본 제공 대시보드에는 Unity AI Gateway 모델 서비스 사용량, 성능 및 비용에 대한 포괄적인 가시성이 있습니다. 여기에는 여러 페이지 추적 요청, 토큰 사용량, 대기 시간 메트릭, 오류 비율, 비용 분석, 외부 MCP 서버 트래픽 및 코딩 에이전트 작업이 포함됩니다.
대시보드는 기본적으로 작업 영역 간 분석을 제공합니다. 모든 대시보드 페이지는 날짜 범위 및 작업 영역 ID를 기준으로 필터링할 수 있습니다.
- 개요 탭: 일일 요청 볼륨, 시간에 따른 토큰 사용량 추세, 토큰 사용량별 상위 사용자 수 및 총 고유 사용자 수를 포함한 상위 수준 사용 메트릭을 표시합니다. 이 탭을 사용하여 전체 Unity AI 게이트웨이 활동의 빠른 스냅샷을 가져오고 가장 활성 사용자 및 모델을 식별합니다.
- 성능 탭: 대기 시간 백분위수(P50, P90, P95, P99), 시간-첫 번째 바이트, 오류 비율 및 HTTP 상태 코드 배포를 포함한 주요 성능 메트릭을 추적합니다. 이 탭을 사용하여 모델 서비스 상태를 모니터링하고 성능 병목 상태 또는 안정성 문제를 식별합니다.
- 사용 탭: 모델 서비스, 작업 영역 및 요청자별 자세한 사용량 분석을 표시합니다. 이 탭에는 토큰 사용 패턴, 요청 배포 및 캐시 적중 비율이 표시됩니다.
- 비용 관찰 탭: 모델 서비스, 대상 모델, 사용자, 서비스 태그 및 요청 태그별 비용 분석을 표시합니다. 이 탭에는 외부 모델에 대한 예상 비용도 포함됩니다. Unity AI 게이트웨이 비용 모니터링을 참조하세요.
- 외부 MCP 서버 탭: 외부 MCP 서버 트래픽에 대한 요청 볼륨, 오류율, 사용자 및 연결 및 일일 사용 추세를 표시합니다.
- 코딩 에이전트 탭: 커서, 클로드 코드, Gemini CLI 및 Codex 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 |
endpoint_id |
STRING | Unity AI 게이트웨이 모델 서비스의 고유 ID입니다. | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
endpoint_name |
STRING | Unity AI 게이트웨이 모델 서비스의 이름입니다. | databricks-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 | 대상 모델 또는 공급자의 이름입니다. | databricks-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 |
구조 | 유추 호출에 대한 시스템 생성 메타데이터입니다. 호출을 source시작한 서비스 또는 경로를 포함합니다. |
{"source": "EXTERNAL_CLIENT"} |
input_tokens |
LONG | 입력 토큰의 수입니다. | 100 |
output_tokens |
LONG | 출력 토큰의 수입니다. | 100 |
total_tokens |
LONG | 총 토큰 수(입력 + 출력)입니다. | 200 |
token_details |
구조 | 자세한 토큰 분석에는 cache_read_input_tokens, cache_creation_input_tokens, 및 output_reasoning_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", ...}]} |
사용량 추적에 대한 태그 요청
요청 태그는 호출자가 개별 요청에 연결하는 사용자 지정 키-값 쌍입니다. 요청 태그를 사용하여 프로젝트, 팀, 환경, 최종 사용자 또는 조직과 관련된 다른 차원별 사용량을 특성화합니다. 요청 태그는 테이블에 기록 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;