モデルの使用状況を追跡する

このページでは、使用状況追跡システムテーブルを使用して Unity Gateway サービスの使用状況を監視する方法について説明します。

使用状況追跡テーブルは、モデルサービス、モデルプロバイダーサービス、および MCP サービスのリクエストとレスポンスの詳細をキャプチャします。モデルリクエストの場合、トークン使用量やレイテンシーなどのメトリクスが記録されます。MCP リクエストの場合、呼び出しおよびサービスのメタデータを記録します。このテーブルを使用して、ユーザーの監視、コストの追跡、サービスの使用状況とパフォーマンスの分析を行います。

使用状況の追跡は、Databricksが提供するモデルサービスへのai_queryリクエストもキャプチャします。

アカウント管理者とワークスペース管理者は、ガバナンスハブのAI ページで、AI 使用状況の統合された概要を確認できます。

要件

• Unity Gatewayがサポートされているリージョン内のDatabricksワークスペース。
• ワークスペースでUnity Catalog有効化されていること。 Unity Catalog のワークスペースを有効にする方法をご覧ください。

価格

使用状況の追跡は、Unity AIゲートウェイの有料機能です。Databricks は、system.ai_gateway.usage テーブルにログが記録された使用状況に対して課金します。Unity AIゲートウェイの価格を参照してください。

使用状況テーブルを照会する

Unity Gatewayは、使用状況データをsystem.ai_gateway.usageシステムテーブルにlogsします。UIでテーブルを表示したり、Databricks SQLやノートブックからテーブルにクエリーを実行したりできます。

注記

system.ai_gateway.usage テーブルをdefaultで表示またはクエリーするには、アカウント管理者ロールとメタストア管理者ロールの両方が必要です。管理者は システムテーブルへのアクセスを管理して、ユーザー、グループ、および Service Principal の権限を制御できます。

UIでテーブルを表示するには、モデルサービスページの使用状況トラッキングテーブルリンクをクリックして、Catalog Explorerでテーブルを開きます。

Databricks SQLまたはノートブックからテーブルをクエリするには：

SQL

SELECT * FROM system.ai_gateway.usage;

プロンプト

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 ページのスタンドアロンの ダッシュボードを作成 、 ダッシュボードを表示 、および 更新 ボタンを使用してください。

組み込みの使用状況ダッシュボードを作成する

アカウント管理者は、組み込みのUnity AIゲートウェイ使用状況ダッシュボードを作成して、使用状況の監視、コストの追跡、モデルサービスのパフォーマンスと消費に関する知見を得ることができます。Unity AIゲートウェイページで、右上にある ガバナンス をクリックし、 使用状況ダッシュボードの作成 をクリックします。ダッシュボードのクエリーを実行するwarehouseは自動的に選択されます。

注記

ダッシュボードの作成は、system.ai_gateway.usage テーブルに対する SELECT 権限が必要なため、アカウント管理者に制限されています。ダッシュボードのデータは、usage テーブルの保持ポリシーの対象となります。「利用可能なシステムテーブル」を参照してください。

組み込みの使用状況ダッシュボードの新しいバージョンが利用可能な場合、アカウント管理者は Unity Gateway ページの Govern ドロップダウンにあるダッシュボードバージョンの行で 更新 をクリックできます。

ダッシュボードを管理するには、以下のダッシュボード構成オプションを使用できます。

• スコープ : ダッシュボードをアカウントにスコープするか、ワークスペースにスコープするかを選択します。
• 権限 : クエリをダッシュボード所有者の権限で実行するか、各閲覧者の権限で実行するかを選択します。共有データ権限とは何ですか？を参照してください。
• 自動更新 ：このオプションを有効にすると、新しいバージョンが利用可能になり、アカウント管理者が Unity Gateway ページにアクセスするたびに、ダッシュボードが自動的に更新されます。

ダッシュボードがバージョン0.3以降に更新されると、6時間ごとにダッシュボードを更新するスケジュールが自動的に作成されます。必要に応じて、このスケジュールはLakeviewダッシュボードで無効にできます。スケジュールを作成するを参照してください。

使用状況ダッシュボードを表示

ダッシュボードを表示するには、Unity Gatewayページの右上にある [Govern] をクリックし、 [Usage Dashboard] をクリックします。ダッシュボードが新しいtabで開きます。組み込みダッシュボードでは、Unity Gatewayモデルサービスの使用状況、パフォーマンス、コストを包括的に可視化できます。これには、リクエスト、トークン消費量、レイテンシメトリクス、エラー率、コストの内訳、外部MCPサーバーのトラフィック、コーディングエージェントのアクティビティを追跡する複数のページが含まれます。

このダッシュボードは、デフォルトでクロスワークスペースのアナリティクスを提供します。すべてのダッシュボードページは、日付範囲およびワークスペース ID でフィルタリングできます。

• Overview tab ：日次リクエスト数、トークン使用量の経時的傾向、トークン消費量別のトップユーザー、合計ユニークユーザー数など、高レベルの使用状況メトリクスを表示します。このtabを使用して、Unity Gateway 全体のアクティビティのクイックなスナップショットを取得し、最もアクティブなユーザーとモデルを特定します。
• **パフォーマンス タブ**: レイテンシーパーセンタイル（P50、P90、P95、P99）、ファーストバイトまでの時間、エラー率、HTTPステータスコードの分布など、主要なパフォーマンスメトリクスを追跡します。このタブを使用して、モデルサービスの正常性を監視し、パフォーマンスのボトルネックや信頼性の問題を特定します。
• 使用状況タブ ：モデルサービス、ワークスペース、およびリクエスターごとの詳細な消費内訳が表示されます。このタブには、トークンの使用パターン、リクエストの分布、およびキャッシュヒット率が表示されます。
• コスト可観測性tab : モデルサービス、ターゲットモデル、ユーザー、サービス タグ、リクエスト タグごとのコスト内訳を表示します。このtabには、外部モデルの推定コストも含まれます。「Unity Gateway のコストを分析する」を参照してください。
• 外部 MCP サーバータブ : 外部 MCP サーバーのトラフィックに関するリクエスト量、エラー率、ユーザーと接続、日次使用傾向を表示します。
• Coding Agents tab ：Claude Code、Codex CLI、Cursor、Gemini CLI などの統合されたコーディング エージェントからのアクティビティを追跡します。このtabには、開発者ツールの使用状況を監視するためのアクティブな日数、コーディング セッション、commit、追加または削除されたコード行などのメトリクスが表示されます。詳細については、コーディング エージェント ダッシュボードを参照してください。

使用状況テーブルスキーマ

system.ai_gateway.usageテーブルは次のスキーマを持っています:

列名	Type	説明	例
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	マップ	作成時または更新時に Unity Catalog セキュリティ保護可能なオブジェクトに適用されるリソースタグ。サービスに対するすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとに使用量を分類するのに役立ちます。	{"team": "engineering"}
endpoint_id	STRING	Unity AIゲートウェイモデルサービスの一意のID。	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	STRING	Unity Gatewayモデルサービスの名前。	system.ai.gpt-5-2
endpoint_tags	マップ	作成または更新時にモデルサービスで設定されたタグ。これらはモデルサービスへのすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとにサービスを分類するのに役立ちます。	{"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	宛先モデルまたはプロバイダーの名前。	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	The type of API call (for example, chat, completions, or embeddings).	mlflow/v1/chat/completions
request_tags	マップ	Databricks-Ai-Gateway-Request-Tags HTTP ヘッダーを使用して個々のリクエストと共に送信される、ユーザー提供のタグ。リクエストタグを使用して、使用状況を特定のプロジェクト、チーム、環境、またはエンドユーザーに帰属させます。使用状況追跡用のリクエストのタグ付けおよびリクエストのタグ付けを参照してください。	{"project": "chatbot", "team": "ml-platform"}
invocation_metadata	構造体	リクエストの送信元、モデルプロバイダーによって報告されたサービス層、およびリクエストで Claude サブスクリプションが使用されたかどうかに関する情報。	{"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
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_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	構造体	フォールバックの試行に関するルーティングの詳細。リクエスト中に試行された各モデルに対して、priority、action、destination、destination_id、status_code、error_code、latency_ms、start_time、およびend_timeを含むattempts配列が含まれています。	{"attempts": [{"priority": "1", ...}]}
mcp_metadata	構造体	呼び出されたツール、サーバーの種類、JSON-RPC操作など、MCPサービスへのリクエストの詳細。MCP_SERVICE行分が入力されました。	{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata	構造体	セッションおよびクライアントのコンテキスト（セッションおよびサブエージェントID、コーディングエージェントの名前とバージョン、クライアントインターフェイス、推論の努力量、スマートルーティングのレシピなど）。これらのフィールドを使用して、関連するリクエストをグループ化し、エージェントまたはセッションごとに使用状況を分析します。	{"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode	STRING	リクエストの認証に使用されるDatabricksの認証情報の種類：個人アクセストークン（PAT）またはOAuthトークン（OAUTH）。	OAUTH

列名	Type	説明	例
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	マップ	作成時または更新時に Unity Catalog セキュリティ保護可能なオブジェクトに適用されるリソースタグ。サービスに対するすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとに使用量を分類するのに役立ちます。	{"team": "engineering"}
endpoint_id	STRING	Unity AIゲートウェイモデルサービスの一意のID。	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	STRING	Unity Gatewayモデルサービスの名前。	system.ai.gpt-5-2
endpoint_tags	マップ	作成または更新時にモデルサービスで設定されたタグ。これらはモデルサービスへのすべてのリクエストに適用され、チーム、コストセンター、またはプロジェクトごとにサービスを分類するのに役立ちます。	{"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	宛先モデルまたはプロバイダーの名前。	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	The type of API call (for example, chat, completions, or embeddings).	mlflow/v1/chat/completions
request_tags	マップ	Databricks-Ai-Gateway-Request-Tags HTTP ヘッダーを使用して個々のリクエストと共に送信される、ユーザー提供のタグ。リクエストタグを使用して、使用状況を特定のプロジェクト、チーム、環境、またはエンドユーザーに帰属させます。使用状況追跡用のリクエストのタグ付けおよびリクエストのタグ付けを参照してください。	{"project": "chatbot", "team": "ml-platform"}
invocation_metadata	構造体	リクエストの送信元、モデルプロバイダーによって報告されたサービス層、およびリクエストで Claude サブスクリプションが使用されたかどうかに関する情報。	{"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
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_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	構造体	フォールバックの試行に関するルーティングの詳細。リクエスト中に試行された各モデルに対して、priority、action、destination、destination_id、status_code、error_code、latency_ms、start_time、およびend_timeを含むattempts配列が含まれています。	{"attempts": [{"priority": "1", ...}]}
mcp_metadata	構造体	呼び出されたツール、サーバーの種類、JSON-RPC操作など、MCPサービスへのリクエストの詳細。MCP_SERVICE行分が入力されました。	{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata	構造体	セッションおよびクライアントのコンテキスト（セッションおよびサブエージェントID、コーディングエージェントの名前とバージョン、クライアントインターフェイス、推論の努力量、スマートルーティングのレシピなど）。これらのフィールドを使用して、関連するリクエストをグループ化し、エージェントまたはセッションごとに使用状況を分析します。	{"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode	STRING	リクエストの認証に使用されるDatabricksの認証情報の種類：個人アクセストークン（PAT）またはOAuthトークン（OAUTH）。	OAUTH

ネストされた列のスキーマ

次の表は、ネストされた STRUCT 列内のフィールドについて説明しています。フィールドの可用性は、リクエストに使用されるサービス、モデル、およびクライアントによって異なります。

呼び出しとトークンのメタデータ

フィールドのパス	Type	説明
invocation_metadata.source	STRING	リクエストを開始したアプリケーション、サービス、または API。使用量をそのソースに帰属させるには、このフィールドを使用します。値には、AI_PLAYGROUND、EXTERNAL_CLIENT、AI_QUERY、GUARDRAIL、および MANAGED_AGENT が含まれます。
invocation_metadata.service_tier	STRING	default や priority など、推論レスポンスでモデルプロバイダーによって報告されるサービス層。このフィールドを使用して、プロバイダーの価格プラン全体の使用量を比較します。
invocation_metadata.relayed	BOOLEAN	呼び出し元の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	リクエストの一部として行われた課金対象のウェブ検索クエリーの数。

フィールドのパス	Type	説明
invocation_metadata.source	STRING	リクエストを開始したアプリケーション、サービス、または API。使用量をそのソースに帰属させるには、このフィールドを使用します。値には、AI_PLAYGROUND、EXTERNAL_CLIENT、AI_QUERY、GUARDRAIL、および MANAGED_AGENT が含まれます。
invocation_metadata.service_tier	STRING	default や priority など、推論レスポンスでモデルプロバイダーによって報告されるサービス層。このフィールドを使用して、プロバイダーの価格プラン全体の使用量を比較します。
invocation_metadata.relayed	BOOLEAN	呼び出し元の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_SERVICE 行の mcp_metadata に入力されます。

フィールドのパス	Type	説明
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 など)。

フィールドのパス	Type	説明
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 フィールドは、セッション内のリクエストを関連付け、コーディングエージェント、クライアントインターフェイス、およびリクエスト設定を区別するのに役立ちます。対応する情報がクライアントまたはリクエストから得られる場合、各フィールドに入力されます。

フィールドのパス	Type	説明
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	クライアントによって選択されたスマートルーティングレシピの名前。ルーティングレシピごとに使用量をグループ化するために使用します。

フィールドのパス	Type	説明
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テーブルにログ記録され、使用状況データをフィルタリング、集計、分析するために使用できます。

個々のリクエストにタグを付けるには、Databricks-Ai-Gateway-Request-Tags HTTPヘッダーに、文字列キーを文字列値にマッピングするJSONオブジェクトを含めます。リクエストタグは使用状況テーブルのrequest_tags列にログ記録され、および推論テーブルにログ記録されます。

REST API、OpenAI SDK、Anthropic SDK を使用してリクエストタグを設定する方法の例については、リクエストのタグ付けを参照してください。

たとえば、リクエストタグを使用してプロジェクト別に利用状況を集計できます：

SQL

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;

制限事項

• Unity Gateway は、1 MiB を超える非ストリーミング、非埋め込みのレスポンスに対するトークン使用量を追跡しません。

その他のリソース

• Unity GatewayによるAIガバナンス
• カスタムモデルサービスを作成する
• 基盤モデルとエンべディングモデルのクエリー
• コーディングエージェントの統合
• リクエストと応答を推論テーブルにLogsする
• モデルサービスおよびMCPサービスにレート制限を適用する