モデルの使用状況の追跡

system.ai_gateway.usageサービスの利用状況をシステムテーブルで監視してください。 AI クエリ、コーディングエージェント、Databricksアプリ、AI Playground、その他のアプリケーションなど、さまざまなソースからのモデルサービス、モデルプロバイダーサービス、MCPサービスへのリクエストをキャプチャします。

使用記録には、リクエスターおよびサービスの詳細、応答状況、モデルトークンの使用状況と遅延、MCPコールのメタデータ、コーディングエージェントのセッションメタデータが含まれます。 テーブルをクエリしてカスタム分析を行うか、 組み込みの使用ダッシュボード を使って使用状況、支出、採用率、パフォーマンスを監視できます。

アカウントやワークスペース管理者は、Governance Hubの AIページ でAI利用状況の統合概要も確認できます。

Requirements

使用状況テーブルのクエリを実行する

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のページからダッシュボードを作成できます:

  1. Govern > Create Usage Dashboardをクリックしてください。
  2. ワークスペース間の使用状況を分析するには アカウント使用 を選択し、現在のワークスペースに分析を制限するには ワークスペース使用状況 を選択してください。
  3. データ権限の設定:
    • データ権限の共有: ビューアはあなたのデータ アクセス許可を使ってダッシュボード クエリを実行します。
    • 個別のデータ権限:各ビューアは自分のデータ権限を使ってダッシュボードのクエリを実行します。
  4. 自動更新とスケジュールされたデータ更新を有効にするかどうかを選択してください。
  5. [セットアップと公開] をクリックします。

デフォルトのSQLウェアハウスは自動的に選択されます。 ダッシュボードのクエリを実行するアイデンティティは、基盤となるシステムテーブルへのアクセスが必要です。 システム テーブルへのアクセスを付与およびダッシュボードのデータ権限を参照してください。

ai-gateway ダッシュボード オプションの更新

メモ

Governドロップダウンがないワークスペースでは、Unity Gatewayページの「Create Dashboard」「View Dashboard」「Update」のスタンドアロンボタンを使ってください。

ダッシュボードを探索する

Govern > Usage Dashboard をクリックして、新しいタブでダッシュボードを開きます。

ai-gateway の使用状況ダッシュボード

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ワークロードのコスト表示」をご覧ください。

その他のリソース