メインコンテンツまでスキップ
に最終更新

統合トレーステーブルを使用してすべてのAIアクティビティを監視する

備考

ベータ版

統合トレーステーブルはベータ版です。Unity AI Gateway は一般提供されていますが、そのベータ機能は個別に有効にする必要があります。アカウント管理者は、アカウントコンソールの [プレビュー] ページから Enhanced Unity AI Gateway ベータ機能を有効にする必要があります。Databricksのプレビューを管理するを参照してください。

統合トレーステーブルを使用すると、Unity AIゲートウェイサービス全体のすべてのアクティビティを監視、デバッグ、保護、および監査するための単一の場所が提供されます。

メタストア管理者が統合トレースを一度設定します。その後、すべての Unity AI Gateway トラフィックは、Endpoint ごとのセットアップなしで自動的にログに記録されます。

重要

default、トレーステーブルを作成したメタストア管理者のみがそのテーブルを読み取ることができます。所有者が Unity Catalog を介して明示的にアクセス権を付与しない限り、Endpoint の所有者やセキュリティチームを含む他のユーザーは、そのテーブルをクエリーできません。「権限とアクセス制御」を参照してください。

要件​

  • お客様のアカウントで Enhanced Unity AI Gateway のプレビュー版が有効になりました。「Databricks プレビューの管理」を参照してください。
  • ワークスペースでUnity Catalog有効化されていること。
  • 統合トレースを設定するためのメタストア管理者ロール。
  • CREATE TABLE、ターゲットの Unity Catalog カタログおよびスキーマにおける USE CATALOG および USE SCHEMA の権限。
  • テーブルをクエリーするには：トレーステーブルに対する SELECT 権限。By default, メタストア管理者のみがクエリーを実行できます。他のユーザーにアクセス権を付与する方法については、「権限とアクセス制御」を参照してください。

統合トレーステーブルとは​

統合トレーステーブルは、すべてのUnity AIゲートウェイサービスにおけるすべてのリクエストとレスポンスをOpenTelemetry(「OTel」)形式のUnity Catalogテーブルにまとめます。推論テーブルに比べて、3つの利点があります。

  • 完了。 すべてのサービスにわたるすべてのアクティビティが1か所に集約され、Endpointごとのセットアップは不要です。
  • 強制可能。 メタストア管理者が一度テーブルを作成すると、ログ記録が無効になっているサービスによる死角が生じることなく、すべてのサービスにログ記録が適用されます。
  • オープン。 OpenTelemetry 標準に基づいて構築されているため、カスタムの後処理なしで、あらゆるツールがデータを直接利用できます。

一般的な用途：

  • デバッグ： trace_id でフィルタリングして、失敗したエージェントランのすべてのステップをリプレイします。service_name と status.code でフィルタリングして、特定のEndpoint上のすべてのエラーを検索します。
  • AI 使用状況のアナリティクス: AI 関数を使用して LLM（コーディングアシスタントを含む）との対話を分析し、呼び出し元全体のパターンを把握して、組織内で AI が提供する価値を理解します。
  • トークン使用量の削減: AI関数を使用して、LLMまたはMCPへの呼び出しにおける一般的なエラーパターンを分析し、エージェントやコーディングアシスタントの有効性を向上させる方法を理解します。
  • セキュリティとコンプライアンス: すべてのスパンは、リクエスターの ID、Endpoint名、および完全なリクエストペイロードを記録するため、脅威の検出と調査のためにセキュリティツールにフィードできます。
  • 監査可能性： ユーザー、Endpoint、または時間範囲ごとの AI アクティビティを確認します。
注記

トレースの配信はベストエフォート型（制限事項を参照）であるため、統合トレーステーブルは Databricks 監査 Logs を置き換えるものではなく、補完するものです。コンプライアンスのための記録システムとして、引き続きaudit Logsを使用してください。

統合トレーステーブルと推論テーブルの比較​

統合トレーステーブルは、新規デプロイメントで推奨されるアプローチです。推論テーブルは引き続き利用可能ですが、単一のモデルサービスEndpointの要求/応答モニタリング専用に設計されています。推論テーブルの詳細については、「推論テーブルへのリクエストと応答のLogs」を参照してください。

統合トレーステーブル

推論テーブル

スコープ

すべてのUnity AI GatewayモデルサービスとMCPサービスを1つのテーブルに集約

Per model serving Endpoint, one table each

設定

メタストア管理者による 1 回限りのセットアップ。メタストアにアタッチされているすべてのワークスペースのすべてのサービスに適用されます

Endpointごとに有効にする必要があります

スキーマ

OpenTelemetryスパン

Databricks固有（後処理が必要）

エージェントワークフロー

すべてのホップが 1 つのテーブルに格納されます。完全なマルチホップトレースを再構築するための共有トレース ID は近日公開予定です。

Endpointごとのテーブルに断片化

MLflow の互換性

スパンは、MLflowツールが直接読み取れるMLflow互換のOTelスキーマを使用します

手動トレース抽出が必要です

所有者

テーブルを作成するメタストア管理者

Endpointの所有者

アクセス制御

default: メタストア管理者のみ。Unity Catalogの権限とABAC行フィルターポリシーを使用して他のユーザーにアクセス権を付与する

EndpointごとのUnity Catalog ACLの分離

統合トレーステーブル

推論テーブル

スコープ

すべてのUnity AI GatewayモデルサービスとMCPサービスを1つのテーブルに集約

Per model serving Endpoint, one table each

設定

メタストア管理者による 1 回限りのセットアップ。メタストアにアタッチされているすべてのワークスペースのすべてのサービスに適用されます

Endpointごとに有効にする必要があります

スキーマ

OpenTelemetryスパン

Databricks固有（後処理が必要）

エージェントワークフロー

すべてのホップが 1 つのテーブルに格納されます。完全なマルチホップトレースを再構築するための共有トレース ID は近日公開予定です。

Endpointごとのテーブルに断片化

MLflow の互換性

スパンは、MLflowツールが直接読み取れるMLflow互換のOTelスキーマを使用します

手動トレース抽出が必要です

所有者

テーブルを作成するメタストア管理者

Endpointの所有者

アクセス制御

default: メタストア管理者のみ。Unity Catalogの権限とABAC行フィルターポリシーを使用して他のユーザーにアクセス権を付与する

EndpointごとのUnity Catalog ACLの分離

統合トレーステーブルの有効化​

これは、メタストア管理者が実行する1回限りの操作です。テーブルは、選択したUnity Catalogパス（例：<catalog>.<schema>.unity_gateway_otel_spans）に存在します。

ヒント

トレーステーブルを専用のカタログまたはスキーマに保存します。分離により、他のカタログやスキーマからの権限によってトレースデータが意図せず公開されることを防ぎます。テーブルを作成したメタストア管理者がその所有者となり、アクセス権を制御します。他のユーザーにクエリーアクセス権を付与するには、権限とアクセス制御に記載されている通り、ABACをセットアップすることをお勧めします。

  1. ワークスペースのサイドバーで、 AI Gateway をクリックします。
  2. Govern > Traces > Set up tracing をクリックします。
  3. トレーステーブルを作成する カタログ と スキーマ を選択します。
  4. [作成] をクリックして、トレーステーブルを作成します。

統合トレーステーブルを使用する​

重要

By default、メタストア管理者のみがトレーステーブルをクエリーできます。共有する前に、各ユーザーが適切なトレースのみを表示できるように、ABAC 行フィルターポリシーを設定してください。以下の「権限とアクセス制御」を参照してください。

UI でトレースを表示する​

  1. ワークスペースのサイドバーで、 AI Gateway > Govern > Traces tabをクリックします。

トレースビューには、以下のコントロールが用意されています。

  • 検索： 現在の画面内のコンテンツ全体に対する全文検索。
  • 時間範囲： 時間ウィンドウでトレースをフィルタリングします（default：過去24時間）。
  • フィルター: サービス (Endpoint名)、 プリンシパル (リクエスター)、 サービスタイプ 、 状態 、または 実行時間 でフィルターします。
  • 列： 列の表示または非表示を切り替えます。
  • warehouse: トレーステーブルに対してクエリーを実行するために使用するSQLウェアハウスを選択します。

検索、時間範囲、フィルターコントロールを備えたトレースtab

Genie Codeでクエリーを作成する​

Genie Codeはワークスペース全体で利用可能です。サイドバーからGenie Codeを開き、トレーステーブルに対するSQLクエリーを作成するよう依頼します。Genie CodeはUnity Catalogのテーブルスキーマを自動的に認識します。

プロンプトの例：

  • 「過去24時間にcustomer-support-bot Endpointで発生したすべてのレート制限エラーを表示して」
  • 「先週、p99応答時間が最も長かったユーザーは誰ですか？」
  • 「エージェントが3回以上の下流呼び出しを行ったすべてのトレースを検索」

Genie Code は SQL を生成し、ノートブックまたは SQL エディターで直接実行できます。

SQL またはノートブックを使用したクエリー​

テーブルはtimeでクラスタリングされています。最高のパフォーマンスを得るには、この列をWHERE句に含めてください。

<catalog>.<schema>.<table_name> をトレーステーブルのパスに置き換えます。

SQL
-- All spans for a specific trace
SELECT * FROM <catalog>.<schema>.<table_name>
WHERE trace_id = 'afdd29f3a069482f8b102380ba0fb3c8'
ORDER BY start_time_unix_nano;

-- All errors on a specific endpoint in the last 24 hours
SELECT trace_id, name, status, attributes
FROM <catalog>.<schema>.<table_name>
WHERE service_name = '<catalog>.<schema>.<model>'
  AND status.code = 'STATUS_CODE_ERROR'
  AND time >= current_timestamp() - INTERVAL 1 DAY;

-- Root spans only (one row per request), with requester and HTTP status
SELECT trace_id, name,
  attributes:`enduser.id`::string AS requester
  attributes:`http.response.status_code`::int AS status_code,
  status.code
FROM <catalog>.<schema>.<table_name>
WHERE parent_span_id IS NULL
  AND service_name = '<catalog>.<schema>.<model>';

権限とアクセス制御​

すべてのUnity AI Gatewayトラフィックは1つのテーブルに集約されるため、Endpointごとに個別の権限を維持するのではなく、1か所でアクセスを管理できます。

By default, メタストア管理者のみがトレーステーブルをクエリーできます。テーブルを作成したメタストア管理者が、その所有者になります。他のユーザーにクエリーへのアクセス権を付与するには、テーブル所有者がテーブルに対して SELECT、スキーマに対して USE SCHEMA、カタログに対して USE CATALOG を付与する必要があります。行フィルターがない場合、これらの権限を持つすべてのユーザーがワークスペース内のすべてのサービスのトレースを表示できるため、Databricks ではアクセス権を付与する前に ABAC 行フィルターポリシーを適用することを推奨しています。

ABACポリシーによるアクセスをスコープ化​

Databricks では、各ユーザーまたはチームが閲覧すべき行のみにアクセスできるように、属性ベースのアクセス制御（ABAC）の使用を推奨しています。ABAC 行フィルターポリシーは、クエリー実行時に動作する SQL 関数をトレーステーブル（またはその親カタログやスキーマ）に付与します。ユーザーが SELECT * を実行すると、手動で WHERE 句を指定しなくても、自動的に自分の行のみが返され、他のチームのトレースを読み取るリスクもありません。

次の例は一般的なポリシーを実装しています：管理者はすべてのトレースを閲覧でき、Endpointの所有者は自身のサービスのみを閲覧でき、その他のユーザーは何も閲覧できません。

この例では、各サービスが<service_name>-ownersという名前の対応するアカウントグループを持つという規則に従っています。これらのグループは自動的には作成されません。アクセス設定の一環として、管理者は各グループを作成して適切なメンバーを追加する必要があり、新しいEndpointが追加されるたびにこれを繰り返す必要があります。グループが追加されても、フィルター関数とポリシーは変更されません。

  1. フィルター関数を作成します。各行のサービス名を受け取り、現在のユーザーに表示権限がある場合は TRUE を返します。

    SQL
    CREATE OR REPLACE FUNCTION <catalog>.<schema>.ai_traces_filter(svc STRING)
    RETURNS BOOLEAN
    RETURN is_account_group_member('admins')
        OR is_account_group_member(svc || '-owners');

  2. ポリシーがバインドできるように、service_name列にタグを付けます。ABACポリシーは、管理タグによってフィルター関数に列を渡します。

    SQL
    ALTER TABLE <catalog>.<schema>.<table_name>
    ALTER COLUMN service_name SET TAGS ('ai_trace_service' = '');

  3. トレーステーブルに行フィルターポリシーを作成します。

    SQL
    CREATE POLICY ai_traces_filter
    ON TABLE <catalog>.<schema>.<table_name>
    COMMENT 'Restrict trace visibility to service owners and admins'
    ROW FILTER <catalog>.<schema>.ai_traces_filter
    TO `account users`
    FOR TABLES
    MATCH COLUMNS has_tag('ai_trace_service') AS svc
    USING COLUMNS (svc);

  4. 各サービスに対して <service_name>-owners アカウントグループを作成し（存在しない場合）、メンバーを追加して、テーブルのクエリーに必要な権限を付与します。カタログに対して USE CATALOG 、スキーマに対して USE SCHEMA 、テーブルに対して SELECT の権限を付与してください。

    SQL
    GRANT USE CATALOG ON CATALOG <catalog> TO `customer-support-bot-owners`;
    GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `customer-support-bot-owners`;
    GRANT SELECT ON TABLE <catalog>.<schema>.<table_name> TO `customer-support-bot-owners`;

このポリシーが適用されると、クエリーを実行するユーザーに基づいて結果が自動的にフィルタリングされます：

  • SELECT * FROM <table> を実行する customer-support-bot-owners のメンバーは、service_name = 'customer-support-bot' である行のみを表示できます。
  • admins グループのメンバーは、すべての行を表示できます。
  • 他のユーザーには行が表示されません。

新しいエンドポイントが追加されたら、最後のステップを繰り返します。一致する<service_name>-ownersグループを作成し、それにSELECTを付与してください。ポリシーとフィルター関数は変更されません。

完全な ABAC リファレンスについては Unity Catalog における属性ベースのアクセス制御を、その他の行フィルターパターンについては 行フィルターと列マスクの一般的なパターンを参照してください。

PIIのマスキングによるスコープアクセス​

アクセスを拡大するもう1つのアプローチは、PIIを編集したバージョンのテーブルをマテリアライズすることです。編集されたテーブルには、より多くのユーザーをカバーする広範なSELECT権限を付与できます。トレードオフとして、トレースは2回マテリアライズされます。1回目は元のテーブル内の編集されていない形式（厳格なアクセス要件が維持されます）、2回目はより多くのコンシューマーに公開される別のテーブル内の編集された形式です。

Unity Catalog 内の OpenTelemetry トレースから PII を編集するためのリファレンス ソリューションについては、Unity Catalog での OpenTelemetry トレースからの PII の編集を参照してください。

スキーマ​

統合トレーステーブルの各行は、1つの OpenTelemetry スパンです。列の完全なリスト、属性キー、およびポリシー評価イベントフィールドについては、統合トレーステーブルスキーマリファレンスをご覧ください。

制限事項​

  • ログに記録される最大属性サイズは 3 MiB (3,145,728 バイト) です。これを超える属性は切り捨てられます。スパンには databricks.trace.payload_truncated がマークされ、その dropped_attributes_count がインクリメントされます。
  • Trace log delivery is best-effort.ほとんどのトレースは数秒以内に到着しますが、新しいテーブルの場合、トレースの到着までに最大1時間かかることがあります。
  • 401、403、429、または 500 エラーの場合、トレース Logs は保証されません。
  • テーブルスキーマの変更、テーブル名の変更、またはテーブルの削除を行うと、トレーステーブルが Logs を受信できなくなったり、破損したりする可能性があります。
  • Databricks はトレース テーブルのライフサイクルを管理しません。保持ポリシーがない場合、テーブルは無制限に増加します。一定期間後に自動的に行を削除するには、テーブルで 自動有効期間 (Auto-TTL) を有効にします。これにより、バックグラウンドで DELETE と VACUUM が実行されます。保持期間を自身で管理するには、定期的な DELETE をスケジュールして期限切れの行を削除し、続いて VACUUM を実行してストレージを再利用します。VACUUM を単独で実行しても、すでに参照されていないファイルが削除されるだけで、行は削除されません。本番運用でトレーシングを有効にする前に、保持ポリシーを定義してください。
  • By default, メタストア管理者のみがトレーステーブルをクエリーできます。Endpoint作成者またはセキュリティチームが自身のトレースにアクセスできるようにするには、事前にメタストア管理者がABAC行フィルターポリシーを設定し、SELECT、USE SCHEMA、およびUSE CATALOGを付与する必要があります。
このページの見出し