このドキュメントでは、トレース内の Model Armor スパンと、その詳細を表示する方法について説明します。トレースの詳細については、エージェントのトレースを表示するをご覧ください。
Cloud Trace とエージェントのオブザーバビリティについて
トレースは、分散アプリケーションの各部分におけるリクエストのパスを表します。つまり、各トレースは単一のエンドツーエンド オペレーションを表します。トレースは、単一の関数またはオペレーションの記録であるスパンで構成されているため、リクエストのフローを追跡し、レイテンシ データを調べることができます。この情報は、問題の根本原因を特定するのに役立ちます。
Cloud Trace は Cloud de Confiance by S3NSの分散トレース システムです。トレースを探索したり、SQL でトレースデータを分析したりする機能を提供します。ただし、アプリケーション モニタリングや Agent Registry などの多くのCloud de Confiance サービスは、Cloud Trace で管理されているデータを表示できます。これらのサービスを使用すると、使用しているサービスのコンテキストでトレースデータを表示できます。
始める前に
-
Cloud Trace、Cloud Logging、Telemetry、Model Armor の各 API が有効になっていない場合は、有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。 - エージェントのトレースを設定します。
- ゲートウェイまたは Cloud de ConfianceMCP サーバーで Model Armor を構成します。
必要なロール
トレースデータの表示に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- Cloud トレース ユーザー（
roles/cloudtrace.user） - ログビューア（
roles/logging.viewer）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
必要な他のロールについては、Cloud Trace のアクセス制御と Cloud Logging のアクセス制御をご覧ください。
サポートされているペイロード
サポートされているペイロードの一覧については、サポートされているペイロードとサポートされていないペイロードをご覧ください。
サポートされていないペイロードを含むリクエストの場合、Model Armor はエラーを含むスパンを生成します。
Model Armor のスパン名と属性
次の Model Armor スパンを使用できます。
- 親スパン:
apply_guardrail "Google Cloud Model Armor" - 子スパン:
Request Path - 子スパン:
Response Path
以降のセクションでは、Model Armor スパンのすべての属性について説明します。すべての属性がすべてのスパンに存在するわけではありません。これらの属性名は変更される可能性があります。
親スパンの属性
親スパン apply_guardrail "Google Cloud Model Armor" には次の属性があります。
cloud.provider: オペレーションに関連付けられたクラウド プロバイダ。cloud.region: オペレーションが発生した Cloud de Confiance by S3NS リージョン。gcp.project_id: オペレーションが発生したプロジェクトの ID。rpc.system: オペレーションに使用された基盤となるリモート プロシージャ コール（RPC）フレームワークまたはプロトコル（例:grpc）。service.name: オペレーションに関連付けられている Cloud de Confiance サービス。Model Armor スパンの場合、このフィールドの値はmodelarmorです。
リクエストパスの属性
Request Path 子スパンには次の属性があります。
gen_ai.security.target.type: ガードレールが適用されるコンテンツまたはアクションのタイプ。Request Pathスパンでは、これは常にinputです。gen_ai.security.decision.type: Model Armor が適用した判定またはアクション。値modifyは、提供されたテンプレートに従って、Model Armor がコンテンツからセンシティブ データを編集（匿名化）したことを示します。gen_ai.security.decision.code: セキュリティ上の決定の数値コード。gen_ai.security.decision.reason: ユーザーが読める形式の決定理由。gen_ai.security.policy.id: Model Armor テンプレートの完全なリソース名（projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID形式）。gen_ai.security.policy.name: オペレーションに使用された Model Armor テンプレートの名前。gcp.modelarmor.filter.match.state: コンテンツが Model Armor フィルタ（検出器とも呼ばれます）のいずれかに違反したかどうか。gcp.modelarmor.violations: コンテンツが違反した Model Armor フィルタ。値deidentifiedは、提供されたテンプレートに従って Model Armor がコンテンツからセンシティブ データを削除したことを示します。gcp.modelarmor.rai.violations: コンテンツが違反した責任ある AI のカテゴリ。詳細については、責任ある AI の安全フィルタをご覧ください。gcp.modelarmor.sdp.info_types: Sensitive Data Protection フィルタによって識別されたセンシティブ データ型（EMAIL_ADDRESSやPHONE_NUMBERなど）。error.type: 発生したエラーの識別子。
レスポンス パスの属性
Response Path 子スパンには次の属性があります。
gen_ai.security.target.type: ガードレールが適用されるコンテンツまたはアクションのタイプ。Response Pathスパンでは、これは常にoutputです。gen_ai.security.decision.type: Model Armor が適用した判定またはアクション。値modifyは、Model Armor が提供されたテンプレートに従ってコンテンツからセンシティブ データを編集（匿名化）したことを示します。gen_ai.security.decision.code: セキュリティ上の決定の数値コード。gen_ai.security.decision.reason: ユーザーが読める形式の決定理由。gen_ai.security.policy.id: Model Armor テンプレートの完全なリソース名（projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID形式）。gen_ai.security.policy.name: オペレーションに使用された Model Armor テンプレートの名前。gcp.modelarmor.filter.match.state: コンテンツが Model Armor フィルタ（検出器とも呼ばれます）のいずれかに違反したかどうか。gcp.modelarmor.violations: コンテンツが違反した Model Armor フィルタ。値deidentifiedは、提供されたテンプレートに従って Model Armor がコンテンツからセンシティブ データを削除したことを示します。gcp.modelarmor.rai.violations: コンテンツが違反した責任ある AI のカテゴリ。詳細については、責任ある AI の安全フィルタをご覧ください。gcp.modelarmor.sdp.info_types: Sensitive Data Protection フィルタによって識別されたセンシティブ データ型（EMAIL_ADDRESSやPHONE_NUMBERなど）。error.type: 発生したエラーの識別子。
Model Armor スパンの詳細を表示する
Model Armor のスパンとその詳細（属性や DAG など）を表示する手順は次のとおりです。
- Cloud de Confiance コンソールで、[Agent Registry] に移動します。
- プロジェクトを選択します。
- エージェントの名前をクリックします。
- [トレース] タブをクリックします。
- 表示するトレースの ID をクリックします。トレースに Model Armor スパンが含まれている場合、トレースには
apply_guardrail "Google Cloud Model Armor"スパンが含まれます。 トレースを調査します。
- トレースを有向非巡回グラフ（DAG）として表示するには、[グラフ] ビューをクリックします。このビューは、エージェントの実行トレースをノードリンク図として表します。DAG は、さまざまなトレース スパン間の因果関係と依存関係を強調し、あるオペレーションが次のオペレーションをどのようにトリガーするかを示します。グラフの各ノードはスパンです。
- トレースをタイムラインとして表示するには、[タイムライン] ビューをクリックします。タイムラインの各バーはスパンを表します。
スパンをクリックすると、その属性が表示されます。
または、[Cloud Trace で表示] をクリックして、Trace エクスプローラでプロジェクト内のすべてのスパンを表示します。スパンフィルタを適用して、apply_guardrail "Google Cloud Model Armor" スパンを検索します。