system.ai_gateway.usageサービスの利用状況をシステムテーブルで監視してください。
AI クエリ、コーディングエージェント、Databricksアプリ、AI Playground、その他のアプリケーションなど、さまざまなソースからのモデルサービス、モデルプロバイダーサービス、MCPサービスへのリクエストをキャプチャします。
使用記録には、リクエスターおよびサービスの詳細、応答状況、モデルトークンの使用状況と遅延、MCPコールのメタデータ、コーディングエージェントのセッションメタデータが含まれます。 テーブルをクエリしてカスタム分析を行うか、 組み込みの使用ダッシュボード を使って使用状況、支出、採用率、パフォーマンスを監視できます。
アカウントやワークスペース管理者は、Governance Hubの AIページ でAI利用状況の統合概要も確認できます。
Requirements
- Unity Gateway対応リージョン内のAzure Databricksワークスペース。
- ワークスペースに対して有効になっている Unity カタログ。 「Unity Catalog のワークスペースを有効にする」を参照してください。
- デフォルトで
system.ai_gateway.usageテーブルの閲覧またはクエリにはアカウント管理者とメタストア管理者の両方が必要です。 管理者は システムテーブルへのアクセスを管理 し、ユーザー、グループ、サービスプリンシパルの権限を管理できます。
使用状況テーブルのクエリを実行する
Unity Gatewayは使用データを system.ai_gateway.usage システムテーブルにログします。 UI でテーブルを表示したり、Databricks SQL またはノートブックからテーブルにクエリを実行したりすることもできます。
メモ
記録は通常1時間以内に入手可能です。 新しいワークスペースのデータ配信はこれより時間がかかることがあります。
UI でテーブルを表示するには、モデル サービス ページの [使用状況追跡テーブル] リンクをクリックして、カタログ エクスプローラーでテーブルを開きます。
Databricks SQL またはノートブックからテーブルにクエリを実行するには:
SELECT * FROM system.ai_gateway.usage;
Tip
Genie Code はユーザーの代わりにこれを実行できます。 次のプロンプトの例を試してください。
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.
Pricing
使用状況の追跡は、課金対象の Unity Gateway 機能です。 Azure Databrickssystem.ai_gateway.usageテーブルにログする使用量に応じて料金を請求します。 Unity Gatewayの料金をご覧ください。
組み込みの使用状況ダッシュボード
内蔵のUnity Gateway使用ダッシュボードは、モデル、MCPサービス、コーディングエージェント、スキルに関する使用状況、支出、導入状況、パフォーマンスを統合的に表示します。
ダッシュボードを作成する
アカウント管理者はUnity Gatewayのページからダッシュボードを作成できます:
- Govern > Create Usage Dashboardをクリックしてください。
- ワークスペース間の使用状況を分析するには アカウント使用 を選択し、現在のワークスペースに分析を制限するには ワークスペース使用状況 を選択してください。
-
データ権限の設定:
- データ権限の共有: ビューアはあなたのデータ アクセス許可を使ってダッシュボード クエリを実行します。
- 個別のデータ権限:各ビューアは自分のデータ権限を使ってダッシュボードのクエリを実行します。
- 自動更新とスケジュールされたデータ更新を有効にするかどうかを選択してください。
- [セットアップと公開] をクリックします。
デフォルトのSQLウェアハウスは自動的に選択されます。 ダッシュボードのクエリを実行するアイデンティティは、基盤となるシステムテーブルへのアクセスが必要です。 システム テーブルへのアクセスを付与およびダッシュボードのデータ権限を参照してください。
メモ
Governドロップダウンがないワークスペースでは、Unity Gatewayページの「Create Dashboard」「View Dashboard」「Update」のスタンドアロンボタンを使ってください。
ダッシュボードを探索する
Govern > Usage Dashboard をクリックして、新しいタブでダッシュボードを開きます。
| Tab | 分析 |
|---|---|
| Overview | 使用状況、トークン、アクティブユーザー、コーディングエージェントセッションを確認しましょう。 モデルやユーザーを支出、支出傾向、トークンやリクエストごとの支出で比較できます。 |
| 支出 | モデルやユーザーごとの支出を分析し、トークン消費とキャッシュを比較し、サービス タグやリクエスト タグを通じて支出を割り当てます。 |
| コーディングエージェント | エージェントの採用、ハーネスの使用、セッション、トークン消費、サブエージェントを比較してください。 推定支出順に並んだ個々のセッションを調査しましょう。 |
| MCPs | ツールの呼び出しやアクティブユーザーを追跡し、頻繁に使われるサービスやツールを特定し、利用元を比較します。 |
| スキル | スキルのダウンロードと読み込み回数を追跡し、スキルの導入状況を比較し、ユーザーごとのアクティビティを確認できます。 |
| パフォーマンス | モデルとMCPのレイテンシ、最初のバイトまでのストリーミング時間、出力トークン/秒数、キャッシュヒット率、エラー、レート制限付きコールを比較します。 |
| Readme | ダッシュボードの機能、最近の変更点、基盤となるデータソースへのリンクを確認しましょう。 |
分析に重点を置く日付範囲を選択するか、サービスタグキーと1つ以上のサービスタグ値エントリを選択して、使用と支出を特定のチームやプロジェクトに絞り込むことができます。 アカウントスコープ型ダッシュボードには ワークスペースID フィルターも含まれています。 サービスタグフィルターはスキルタブには適用されません。
ダッシュボードを更新
新しいダッシュボードのバージョンが利用可能になった場合、アカウント管理者はGovernドロップダウンのダッシュボードバージョン行で「更新」をクリックできます。 自動更新が有効の場合、アカウント管理者がUnity Gatewayページにアクセスすると新しいテンプレートが適用されます。
更新するとダッシュボードの内容が最新のテンプレートに置き換えられ、カスタマイズが上書きされることもあります。 変更内容を残したい場合は、更新前にコピーを保存してください。
ダッシュボードデータを更新
スケジュールされたデータ更新は 6時間ごとにクエリ結果を更新します。
ダッシュボードで更新スケジュールを管理してください。 「スケジュールを作成する」を参照してください。
使用状況テーブルスキーマ
system.ai_gateway.usage テーブルには、次のスキーマがあります。
| 列名 | タイプ | 説明 | 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 |
INTEGER | 使用レコードのスキーマ バージョン。 | 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 Catalogはサービスの名称を完全に限定しています。 | 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 |
STRUCT |
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 |
Databricks-Ai-Gateway-Request-Tags HTTP ヘッダーを使用して個々の要求と共に送信されるユーザー指定のタグ。 要求タグを使用して、特定のプロジェクト、チーム、環境、またはエンド ユーザーに使用状況を属性付けします。
使用状況の追跡やリクエストタグ付けについてはタグリクエストを参照してください。 |
{"project": "chatbot", "team": "ml-platform"} |
invocation_metadata |
STRUCT | リクエストの発信元、モデルプロバイダーが報告したサービス階層、そしてリクエストがClaudeサブスクリプションを利用したかどうかの情報。 | {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false} |
input_tokens |
LONG | 入力トークンの数。 | 100 |
output_tokens |
LONG | 出力トークンの数。 | 100 |
total_tokens |
LONG | トークンの合計数 (入力 + 出力)。 | 200 |
token_details |
STRUCT |
cache_read_input_tokens、cache_creation_input_tokens、output_reasoning_tokens、cache_creation_5m_input_tokens、cache_creation_1h_input_tokens、file_search_count、num_web_search_queriesを含む詳細なトークンおよびツールの使用状況。 |
{"cache_read_input_tokens": 100, ...} |
response_content_type |
STRING | 応答のコンテンツ タイプ。 | application/json |
status_code |
INT | レスポンスのHTTPステータスコード。 | 200 |
routing_information |
STRUCT |
フォールバック試行のルーティングの詳細。 要求中に試行された各モデルのattempts、priority、action、destination、destination_id、status_code、error_code、latency_ms、およびstart_timeを含むend_time配列が含まれます。 |
{"attempts": [{"priority": "1", ...}]} |
mcp_metadata |
STRUCT | MCPサービスへのリクエストの詳細、呼び出されたツール、サーバータイプ、JSON-RPC 操作などが含まれます。
MCP_SERVICE 行に入力されています。 |
{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"} |
session_metadata |
STRUCT | セッションおよびクライアントコンテキスト(セッションおよびサブエージェントID、コーディングエージェント名とバージョン、クライアントインターフェース、推論作業、スマートルーティングレシピなどが含まれます)。 これらのフィールドを使って関連するリクエストをグループ化し、エージェントやセッションごとの使用状況を分析します。 | {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...} |
auth_mode |
STRING | リクエストを認証するために使われるDatabricksの認証情報タイプは、パーソナルアクセストークン(PAT)またはOAuthトークン(OAUTH)です。 |
OAUTH |
ネストされた列スキーマ
以下の表は、入れ子状 STRUCT 列内のフィールドを説明します。 フィールドの可用性は、リクエストに使用されるサービス、モデル、クライアントによって異なります。
呼び出しとトークンメタデータ
| フィールド パス | タイプ | 説明 |
|---|---|---|
invocation_metadata.source |
STRING | リクエストを開始したアプリケーション、サービス、またはAPIです。 このフィールドを使って使用状況をその出典に帰属してください。 値には AI_PLAYGROUND、EXTERNAL_CLIENT、AI_QUERY、DATABRICKS_APPS、GUARDRAIL、MANAGED_AGENT、ROUTER、WEB_SEARCH、SAFEGUARD_CLASSIFIER が含まれます。 |
invocation_metadata.service_tier |
STRING | 推論応答でモデル提供者が報告するサービス階層、例えば default や priority。 このフィールドを使って、プロバイダーの料金ティア間での使用状況を比較してください。 |
invocation_metadata.relayed |
ブーリアン | そのリクエストが発信者の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に入力されます。
| フィールド パス | タイプ | 説明 |
|---|---|---|
mcp_metadata.tool_name |
STRING | MCPがリクエストで呼び出すツールの名前 tools/call 。 このフィールドを使って、サーバー上の個々のツールの使用状況を分析します。 |
mcp_metadata.server_type |
STRING | リクエストを処理するMCPサーバーのカテゴリ、例えば EXTERNAL や SYSTEM。 |
mcp_metadata.json_rpc_method |
STRING | クライアントが要求する JSON-RPC 操作 tools/call 、例えばツールの呼び出し、ツールの発見 tools/list 、セッション開始の initialize などです。 |
セッションメタデータ
session_metadataフィールドはセッション内のリクエストを関連付け、コーディングエージェント、クライアントインターフェース、リクエスト設定を区別するのに役立ちます。 各フィールドは、対応する情報がクライアントやリクエストから入手可能なときに入力されます。
| フィールド パス | タイプ | 説明 |
|---|---|---|
session_metadata.client_session_id |
STRING | クライアントから提供されたセッションIDです。 同じ会話やコーディングエージェントとのセッション中に出されたリクエストをグループ化するために使うことができます。 |
session_metadata.client_subagent_id |
STRING | クライアントから提供されたサブエージェントIDです。 親セッション内のサブエージェントからのリクエストを区別するために client_session_id と組み合わせて使うことができます。 |
session_metadata.coding_agent |
STRING | リクエストを送信したコーディングエージェントの正規化された名前、例えば claude-code や codex。 |
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 テーブルに記録され、使用状況データのフィルター処理、集計、分析に使用できます。
個々の要求にタグを付けるために、文字列キーを文字列値にマッピングする JSON オブジェクトを含む Databricks-Ai-Gateway-Request-Tags 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を超える非ストリーミング・非埋め込み応答のトークン使用を追跡しません。
-
ai_parse_documentの使用(ai_extractやなど)はUnity Gatewayの使用量の上限に含まれますが、system.ai_gateway.usage表には記録されません。 請求された使用状況を見るには、「 AI Functionワークロードのコスト表示」をご覧ください。