Unity AI Gatewayエンドポイントの使用状況を監視します。
ベータ版
この機能はベータ版です。アカウント管理者は、アカウント コンソールの [プレビュー] ページからこの機能へのアクセスを制御できます。 「Databricks プレビューの管理」を参照してください。
このページでは、使用状況追跡システムテーブルを使用してUnity AI Gatewayエンドポイントの使用状況を監視する方法について説明します。
使用状況追跡テーブルは、エンドポイントのリクエストと応答の詳細を自動的にキャプチャし、使用状況や遅延などの重要なメトリクスを記録します。 この表のデータを使用して、使用状況を監視し、コストを追跡し、エンドポイントのパフォーマンスと消費量を把握することができます。
使用状況の追跡では、Databricksが提供するエンドポイントへのai_queryリクエストも捕捉されます。
要件
- お客様のアカウントでUnity AI Gatewayのプレビュー版が有効になりました。Databricksのプレビューを管理するを参照してください。
- Unity AI Gateway がサポートされるリージョン内のDatabricksワークスペース。
- ワークスペースで Unity Catalog が有効になりました。「Unity Catalog のワークスペースを有効にする」を参照してください。
使用状況テーブルを照会する
Unity AI Gateway は、使用状況データをsystem.ai_gateway.usageシステムテーブルに記録します。 テーブルはUI上で表示することも、Databricks SQLまたはノートブックからクエリを実行することもできます。
system.ai_gateway.usageテーブルを表示またはクエリする権限を持つのはアカウント管理者のみです。
UI でテーブルを表示するには、エンドポイント ページの使用状況追跡テーブル リンクをクリックして、カタログ エクスプローラーでテーブルを開きます。
Databricks SQL またはノートブックからテーブルをクエリするには:
SELECT * FROM system.ai_gateway.usage;
使用状況ダッシュボードの組み込み
組み込みの使用状況ダッシュボードを作成する
アカウント管理者は、 AI Gateway ページで [ダッシュボードの作成] を クリックして組み込み Unity AI Gateway 使用状況ダッシュボードを作成し、使用状況を監視し、コストを追跡し、エンドポイントのパフォーマンスと使用量についての知識を得ることができます。 アカウント管理者は、ダッシュボードクエリの実行に使用されるデータウェアハウスを更新することもできます。この更新は、以降のすべてのクエリに適用されます。
ダッシュボードの作成は、 system.ai_gateway.usageテーブルに対するSELECT権限が必要なため、アカウント管理者のみに制限されています。ダッシュボードのデータは、 usageテーブルの保持ポリシーの対象となります。利用可能なシステムテーブルについては、「どのシステムテーブルが利用できますか？」を参照してください。
組み込みの使用状況ダッシュボードの新しいバージョンが利用可能になった場合、アカウント管理者はAI Gatewayページのダッシュボードアクションメニューから 「更新」 をクリックできます。
ダッシュボードを管理するには、以下のダッシュボード設定オプションを使用できます。
- 範囲 ：ダッシュボードをアカウントまたはワークスペースのどちらに表示するかを選択します。
- 権限 ：クエリをダッシュボード所有者の権限で実行するか、各閲覧者の権限で実行するかを選択します。「共有データ権限とは何か？」を参照してください。
- 自動更新 ：このオプションを有効にすると、新しいバージョンが利用可能になり、アカウント管理者がAI Gatewayページにアクセスするたびに、ダッシュボードが自動的に更新されます。
ダッシュボードがバージョン0.3以降に更新されると、6時間ごとにダッシュボードを更新するスケジュールが自動的に作成されます。必要に応じて、このスケジュールはLakeviewダッシュボードで無効にすることができます。「スケジュールの作成」を参照してください。
使用状況ダッシュボードを表示
ダッシュボードを表示するには、AIゲートウェイページから 「ダッシュボードを表示」 をクリックしてください。ダッシュボードでは、Unity AI Gatewayエンドポイントの使用状況、パフォーマンス、コストを包括的に把握できます。 これには、リクエスト、社内消費、レイテンシ メトリクス、エラー率、コスト内訳、外部 MCP サーバー トラフィック、コーディング エージェント アクティビティを追跡する複数のページが含まれます。
ダッシュボードは、ワークスペース間のアナリティクスを実現します。 すべてのダッシュボード ページは、日付範囲とワークスペース ID でフィルターできます。
- [概要] タブ : 毎日のリクエスト量、長期にわたる 長期間の使用傾向、使用量別の上位ユーザー、合計ユニーク ユーザー数などの高レベルの使用状況メトリクスが表示されます。 このタブを使用して、Unity AI Gateway アクティビティ全体の簡単なスナップショットを取得し、最もアクティブなユーザーとモデルを特定します。
- 「パフォーマンス」タブ : レイテンシのパーセンタイル (P50、P90、P95、P99)、最初のバイトまでの時間、エラー率、HTTP ステータス コードの分布などの主要なパフォーマンス メトリクスを追跡します。 このタブを使用してエンドポイントの健全性を監視し、パフォーマンスのボトルネックや信頼性の問題を特定します。
- 使用状況タブ ：エンドポイント、ワークスペース、リクエスター別の詳細な使用状況の内訳を表示します。このタブには、トークンの使用パターン、リクエストの分布、キャッシュヒット率が表示されます。
- コスト可視性タブ ：エンドポイント、ターゲットモデル、ユーザー、エンドポイントタグ、リクエストタグ別にコストの内訳を表示します。このタブには、外部モデルの概算費用も含まれています。Unity AI Gatewayのコスト監視を参照してください。
- 外部MCPサーバータブ ：外部MCPサーバーのトラフィックに関するリクエスト量、エラー率、ユーザー数と接続数、および日々の使用傾向を表示します。
- コーディング エージェント タブ : Cursor、Claude Code、Gemini CLI、Codex CLI などの統合コーディング エージェントからのアクティビティを追跡します。このタブには、アクティブな日、コーディング セッション、コミット、開発者ツールの使用状況を監視するために追加または削除されたコード行などのメトリクスが表示されます。 詳細については、コーディング エージェント ダッシュボードを参照してください。
使用状況テーブルスキーマ
system.ai_gateway.usageテーブルのスキーマは次のとおりです:
列名 | Type | 説明 | 例 |
|---|---|---|---|
| STRING | アカウントID。 |
|
| STRING | ワークスペース ID。 |
|
| STRING | リクエストの一意の識別子。 |
|
| Integer | 使用状況レコードのスキーマ バージョン。 |
|
| STRING | Unity AI Gatewayエンドポイントの一意のID。 |
|
| STRING | Unity AI Gatewayエンドポイントの名前。 |
|
| マップ | タグは、作成時または更新時にエンドポイント上で設定されます。エンドポイントタグは、エンドポイントへのすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとにエンドポイントを分類するのに役立ちます。使用状況の追跡については、タグのリクエストとエンドポイントを参照してください。 |
|
| 構造体 | エンドポイント メタデータには、 |
|
| TIMESTAMP | リクエストを受信した時のタイムスタンプ。 |
|
| LONG | 合計遅延時間（ミリ秒）。 |
|
| LONG | 最初のバイトまでの時間（ミリ秒）。 |
|
| STRING | 宛先のタイプ (外部モデルや基盤モデルなど)。 |
|
| STRING | 宛先モデルまたはプロバイダーの名前。 |
|
| STRING | 宛先の一意の ID。 |
|
| STRING | リクエストに使用される特定のモデル。 |
|
| STRING | リクエストを行ったユーザーまたはサービスプリンシパルのID。 |
|
| STRING | リクエスタのタイプ (ユーザー、サービスプリンシパル、またはユーザー グループ)。 |
|
| STRING | 要求者の IP アドレス。 |
|
| STRING | リクエストの URL。 |
|
| STRING | 要求者のユーザー エージェント。 |
|
| STRING | API 呼び出しのタイプ (例: チャット、補完、埋め込み)。 |
|
| マップ | ユーザーが指定したタグは、 |
|
| LONG | 入力トークンの数。 |
|
| LONG | 出力トークンの数。 |
|
| LONG | トークンの合計数（入力 + 出力）。 |
|
| 構造体 |
|
|
| STRING | 応答のコンテンツ タイプ。 |
|
| INT | 応答の HTTP ステータス コード。 |
|
| 構造体 | フォールバック試行のルーティングの詳細。リクエスト中に試行された各モデルの |
|
使用状況追跡のためのタグリクエストとエンドポイント
AI Gatewayは、使用状況の追跡と属性付けのために2種類のタグをサポートしています。
- リクエストタグ ：呼び出し元が個々のリクエストに付加するカスタムのキーと値のペア。リクエストタグを使用して、プロジェクト、チーム、環境、エンドユーザー、または組織に関連するその他のあらゆる側面に基づいて使用状況を分類します。
- エンドポイントタグ ：エンドポイント自体に設定されるキーと値のペア。エンドポイントタグは、そのエンドポイントを経由してルーティングされるすべてのリクエストに適用され、チーム、コストセンター、またはアプリケーションごとにエンドポイントを分類するのに役立ちます。
どちらのタグタイプも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;
エンドポイントタグ
エンドポイントタグは、AI Gatewayエンドポイントを作成または更新する際に設定されます。それらは、そのエンドポイントへのすべてのリクエストについて、使用状況テーブルのendpoint_tags列に表示されます。
例えば、エンドポイントタグを使用してチームごとの利用状況を集計できます。
SELECT
endpoint_tags['team'] AS team,
endpoint_name,
COUNT(*) AS request_count,
SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE endpoint_tags['team'] IS NOT NULL
GROUP BY endpoint_tags['team'], endpoint_name
ORDER BY total_tokens DESC;