このドキュメントでは、トレース内の Model Armor スパンと、その詳細を表示する方法について説明します。トレースの詳細については、エージェント トレースを表示するをご覧ください。
Cloud Trace とエージェントのオブザーバビリティについて
トレースは、分散アプリケーションの各部分におけるリクエストのパスを表します。つまり、各トレースは単一のエンドツーエンドのオペレーションを表します。トレースはスパンで構成されています。これは、単一の関数またはオペレーションの記録です。これにより、リクエストのフローを追跡し、レイテンシ データを調べることができます。この情報は、問題の根本原因を特定するのに役立ちます。
Cloud Trace は Google Cloudの分散トレース システムであり、トレースを探索する機能や、SQL でトレースデータを分析する機能を提供します。ただし、Application Monitoring や Agent Registry などの多くのGoogle Cloud サービスでは、Cloud Trace で管理されているデータを表示できます。これらのサービスを使用すると、使用しているサービスのコンテキストでトレースデータを表示できます。
始める前に
-
Cloud Trace、Cloud Logging、Telemetry、Model Armor の各 API がまだ有効になっていない場合は、有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。 - エージェントのトレースを設定します。
- ゲートウェイまたは Google CloudMCP サーバーで 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: オペレーションが発生した Google Cloud リージョン。gcp.project_id: オペレーションが発生したプロジェクトの ID。rpc.system: オペレーションに使用された基盤となるリモート プロシージャ コール（RPC）フレームワークまたはプロトコル（例:grpc）。service.name: オペレーションに関連付けられている Google Cloud サービス。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 など）を表示する手順は次のとおりです。
- Google Cloud コンソールで、[Agent Registry] に移動します。
- プロジェクトを選択します。
- エージェントの名前をクリックします。
- [トレース] タブをクリックします。
- 表示するトレースの ID をクリックします。トレースに Model Armor スパンが含まれている場合、トレースには
apply_guardrail "Google Cloud Model Armor"スパンが含まれます。 トレースを調査します。
- トレースを有向非巡回グラフ（DAG）として表示するには、[グラフ] ビューをクリックします。このビューは、エージェントの実行トレースをノードリンク図として表します。DAG は、異なるトレーススパン間の因果関係と依存関係を強調し、1 つのオペレーションが次のオペレーションをトリガーする方法を示します。グラフの各ノードはスパンです。
- トレースをタイムラインとして表示するには、[タイムライン] ビューをクリックします。タイムラインの各バーはスパンを表します。
スパンをクリックすると、その属性が表示されます。
または、[Cloud Trace で表示] をクリックして、Trace エクスプローラでプロジェクト内のすべてのスパンを表示します。スパンフィルタを適用して、apply_guardrail "Google Cloud Model Armor" スパンを検索します。