このページでは、使用状況追跡システムテーブルを使って Unityゲートウェイ サービスの使用状況を監視する方法を説明しています。
使用状況の追跡テーブルは、モデルサービス、モデルプロバイダーサービス、MCPサービスの要求および応答の詳細を記録します。 モデルリクエストの場合、トークン使用量やレイテンシなどの指標を記録します。 MCPリクエストの場合、通話およびサービスのメタデータを記録します。 テーブルを使ってユーザーの監視、コストの追跡、サービス利用状況やパフォーマンスの分析が可能です。
使用状況の追跡では、Databricks が提供するモデル サービスへの ai_query 要求もキャプチャされます。
アカウントとワークスペースの管理者は、ガバナンス ハブの AI ページで AI の使用状況の統合された概要を表示できます。
Requirements
- Unity Gateway対応リージョン内のAzure Databricksワークスペース。
- ワークスペースに対して有効になっている Unity カタログ。 「Unity Catalog のワークスペースを有効にする」を参照してください。
Pricing
使用状況の追跡は、課金対象の Unity Gateway 機能です。 Azure Databrickssystem.ai_gateway.usageテーブルにログする使用量に応じて料金を請求します。 Unity Gatewayの料金をご覧ください。
使用状況テーブルのクエリを実行する
Unity Gatewayは使用データを system.ai_gateway.usage システムテーブルにログします。 UI でテーブルを表示したり、Databricks SQL またはノートブックからテーブルにクエリを実行したりすることもできます。
メモ
デフォルトで system.ai_gateway.usage テーブルの閲覧またはクエリにはアカウント管理者とメタストア管理者の両方が必要です。 管理者は システムテーブルへのアクセスを管理 し、ユーザー、グループ、サービスプリンシパルの権限を管理できます。
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.
組み込みの使用状況ダッシュボード
メモ
一部のワークスペースには、まだ [ガバナンス ] ドロップダウンが表示されていません。 それらのワークスペースでは、Unity Gatewayページにあるスタンドアロンの 「Create Dashboard」「 View Dashboard」「 Update 」ボタンを使ってください。
組み込み使用ダッシュボードを作成する
アカウント管理者は組み込みのUnity Gateway使用ダッシュボードを作成し、使用状況を監視し、コストを追跡し、モデルサービスのパフォーマンスや消費状況の洞察を得ることができます。 Unity Gatewayのページから右上の Govern をクリックし、「 Create Usage Dashboard」をクリックします。 ダッシュボード クエリを実行するウェアハウスが自動的に選択されます。
メモ
ダッシュボードの作成には、SELECT テーブルに対するsystem.ai_gateway.usageアクセス許可が必要なため、アカウント管理者に制限されます。 ダッシュボードのデータは、 usage テーブルのアイテム保持ポリシーの対象となります。 「使用できるシステム テーブルはどれですか?」を参照してください。
組み込み使用ダッシュボードの新しいバージョンが利用可能になった場合、アカウント管理者はUnity GatewayページのGovernドロップダウンにあるダッシュボードのバージョン行で「更新」をクリックできます。
次のダッシュボード構成オプションを使用して、ダッシュボードを管理できます。
- スコープ: ダッシュボードのスコープをアカウントとワークスペースのどちらにするかを選択します。
- アクセス許可: ダッシュボード所有者のアクセス許可または各ビューアーのアクセス許可を使用してクエリを実行するかどうかを選択します。 「 共有データのアクセス許可とは」を参照してください。
- 自動更新:このオプションを有効にすると、新しいバージョンが利用可能になり、アカウント管理者がUnity Gatewayページにアクセスするたびにダッシュボードが自動的に更新されます。
ダッシュボードがバージョン 0.3 以降に更新されると、6 時間ごとにダッシュボードを更新するスケジュールが自動的に作成されます。 必要に応じて、このスケジュールを Lakeview ダッシュボードで無効にすることができます。 「スケジュールを作成する」を参照してください。
使用状況ダッシュボードを表示する
ダッシュボードを見るには、Unity Gatewayページ右上の「 Govern 」をクリックし、その後 「使用ダッシュボード」をクリックしてください。 ダッシュボードは新しいタブで開きます。組み込みのダッシュボードは、Unity Gatewayモデルのサービス使用状況、パフォーマンス、コストを包括的に把握できます。 要求の追跡、トークン使用量、待機時間のメトリック、エラー率、コストの内訳、外部 MCP サーバー トラフィック、およびコーディング エージェント アクティビティを追跡する複数のページが含まれます。
ダッシュボードでは、既定でクロスワークスペース分析が提供されます。 すべてのダッシュボード ページは、日付範囲とワークスペース ID でフィルター処理できます。
- [概要] タブ: 毎日の要求量、時間の経過に伴うトークン使用量の傾向、トークン消費量別の上位ユーザー数、一意のユーザー数の合計など、高レベルの使用状況メトリックが表示されます。 このタブを使って、Unity Gateway全体の活動を素早く把握し、最もアクティブなユーザーやモデルを特定しましょう。
- [パフォーマンス] タブ: 待機時間のパーセンタイル (P50、P90、P95、P99)、最初のバイトまでの時間、エラー率、HTTP 状態コードの分布など、主要なパフォーマンス メトリックを追跡します。 このタブを使用して、モデル サービスの正常性を監視し、パフォーマンスのボトルネックや信頼性の問題を特定します。
- [使用状況] タブ: モデル サービス、ワークスペース、リクエスター別の詳細な消費量の内訳が表示されます。 このタブには、トークンの使用パターン、要求の分散、キャッシュ ヒット率が表示されます。
- [コスト監視] タブ: モデル サービス、ターゲット モデル、ユーザー、サービス タグ、および要求タグごとのコストの内訳が表示されます。 このタブには、外部モデルの推定コストも含まれます。 詳細は 「Unityゲートウェイコストの分析」を参照してください。
- [外部 MCP サーバー] タブ: 外部 MCP サーバー トラフィックの要求量、エラー率、ユーザーと接続、および毎日の使用状況の傾向が表示されます。
- コーディングエージェントタブ:Claude Code、Codex CLI、Cursor、Gemini CLIなどの統合コーディングエージェントからの活動を追跡します。 このタブには、アクティブな日、コーディング セッション、コミット、開発者ツールの使用状況を監視するために追加または削除されたコード行などのメトリックが表示されます。 詳細については、 コーディング エージェント ダッシュボード を参照してください。
使用状況テーブルスキーマ
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、 GUARDRAIL、 MANAGED_AGENTが含まれます。 |
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を超える非ストリーミング・非埋め込み応答のトークン使用を追跡しません。