Model Armor のトレーススパンを表示する

このドキュメントでは、トレース内の Model Armor スパンと、その詳細を表示する方法について説明します。トレースの詳細については、エージェントのトレースを表示するをご覧ください。

Cloud Trace とエージェントのオブザーバビリティについて

トレースは、分散アプリケーションの各部分におけるリクエストのパスを表します。つまり、各トレースは単一のエンドツーエンド オペレーションを表します。トレースは、単一の関数またはオペレーションの記録であるスパンで構成されているため、リクエストのフローを追跡し、レイテンシ データを調べることができます。この情報は、問題の根本原因を特定するのに役立ちます。

Cloud Trace は Google Cloudの分散トレース システムです。トレースを探索したり、SQL でトレースデータを分析したりする機能を提供します。ただし、アプリケーション モニタリングやエージェント レジストリなど、多くのGoogle Cloud サービスは、Cloud Trace で管理されているデータを表示できます。これらのサービスを使用すると、使用しているサービスのコンテキストでトレースデータを表示できます。

始める前に

  1. Cloud Trace、Cloud Logging、Telemetry、Model Armor の各 API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

    API を有効にする

  2. エージェントのトレースを設定します。
  3. ゲートウェイまたは Google CloudMCP サーバーで Model Armor を構成します。

必要なロール

トレースデータの表示に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

必要なその他のロールについては、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.violation: コンテンツが違反した責任ある AI のカテゴリ。詳細については、責任ある AI の安全フィルタをご覧ください。
  • 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.violation: コンテンツが違反した責任ある AI のカテゴリ。詳細については、責任ある AI の安全フィルタをご覧ください。
  • error.type: 発生したエラーの識別子。

Model Armor スパンの詳細を表示する

Model Armor のスパンとその詳細（属性や DAG など）を表示する手順は次のとおりです。

  1. Google Cloud コンソールで、[エージェント レジストリ] に移動します。

    Agent Registry に移動

  2. プロジェクトを選択します。
  3. エージェントの名前をクリックします。
  4. [トレース] タブをクリックします。
  5. 表示するトレースの ID をクリックします。トレースに Model Armor スパンが含まれている場合、トレースには apply_guardrail "Google Cloud Model Armor" スパンが含まれます。

  6. トレースを調べます。

    • トレースを有向非巡回グラフ（DAG）として表示するには、[グラフ] ビューをクリックします。このビューは、エージェントの実行トレースをノードリンク図として表します。DAG は、さまざまなトレース スパン間の因果関係と依存関係を強調し、あるオペレーションが次のオペレーションをどのようにトリガーするかを示します。グラフ内の各ノードはスパンです。
    • トレースをタイムラインとして表示するには、[タイムライン] ビューをクリックします。タイムラインの各バーはスパンを表します。

  7. スパンをクリックすると、その属性が表示されます。

または、[Cloud Trace で表示] をクリックして、トレース エクスプローラでプロジェクト内のすべてのスパンを表示します。スパンフィルタを適用して、apply_guardrail "Google Cloud Model Armor" スパンを検索します。

次のステップ