ロギングを構成する

このドキュメントでは、次のオペレーションをロギングするように Model Armor を構成する方法について説明します。

• テンプレートを作成、更新、削除するオペレーション
• ユーザー プロンプトまたはモデル レスポンスをサニタイズするオペレーション

Model Armor は、監査ログを使用して管理アクティビティとリソース管理アクティビティを記録します。詳細については、Model Armor の監査ロギングをご覧ください。

ログの料金については、Cloud Logging の料金をご覧ください。処理されるデータ量に応じて、Model Armor の使用料金も適用される場合があります。詳細については、Model Armor の料金をご覧ください。

始める前に

始める前に、次のタスクを完了します。

必要な権限を取得する

Model Armor のロギングを構成するために必要な権限を取得するには、Model Armor テンプレートに対する Model Armor 管理者 （roles/modelarmor.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

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

API を有効にする

Model Armor を使用するには、Model Armor API を有効にする必要があります。

コンソール

1. Model Armor API を有効にします。

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

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

   API の有効化

2. Model Armor を有効にするプロジェクトを選択します。

gcloud

始める前に、Google Cloud CLI で Model Armor API を使用して、次の処理を行います。

1. Google Cloud コンソールで Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

   Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

2. gcloud CLI を使用して API エンドポイントのオーバーライドを設定する。

gcloud CLI を使用して API エンドポイントのオーバーライドを設定する

この手順は、gcloud CLI を使用して Model Armor API を有効にする場合にのみ必要です。gcloud CLI がリクエストを Model Armor サービスに正しく転送するように、API エンドポイントのオーバーライドを手動で設定する必要があります。

次のコマンドを実行して、Model Armor サービスの API エンドポイントを設定します。

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

LOCATION は、Model Armor を使用するリージョンに置き換えます。

トラフィックのサニタイズを設定する

Google と Google Cloud MCP サーバーの場合は、フロア設定でトラフィックのサニタイズを設定します。詳細については、Google とGoogle Cloud MCP サーバーの保護を構成するをご覧ください。

テンプレートでロギングを構成する

テンプレートは、さまざまな安全性とセキュリティのカテゴリのフィルタとしきい値を定義します。Model Armor テンプレートを作成または更新するときに、Model Armor が特定のオペレーションをログに記録するかどうかを指定できます。テンプレート メタデータで次のフラグを使用します。

• log_template_operations: テンプレートの作成、更新、読み取り、削除オペレーションのロギングを有効にするブール値。
• log_sanitize_operations: サニタイズ オペレーション中にユーザー プロンプトとモデル レスポンスのコンテンツ全体をロギングできるブール値。

コンソール

1. Google Cloud コンソールで、[Model Armor] ページに移動します。

   [Model Armor] に移動

2. Model Armor を有効にしたプロジェクトが表示されていることを確認します。

3. [Model Armor ] ページで、[テンプレートを作成] をクリックします。テンプレートの作成の詳細については、Model Armor テンプレートを作成するをご覧ください。

4. [ロギングを構成する] セクションで、ロギングを構成するオペレーションを選択します。

5. [作成] をクリックします。

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

次のように置き換えます。

• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• LOCATION: テンプレートのロケーション。
• TEMPLATE_ID: テンプレートの ID。

Python

このコードを実行するには、まず Python 開発環境を設定し、Model Armor Python SDK をインストールします。

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)
   

次のように置き換えます。

• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• LOCATION: テンプレートのロケーション。
• TEMPLATE_ID: テンプレートの ID。

フロア設定でロギングを構成する

Gemini Enterprise Agent Platform とプロジェクト内の Google および Google Cloud MCP サーバーの Gemini モデルからのトラフィックにフロア設定を適用すると、フロア設定によってサニタイズ オペレーションの安全性とセキュリティ フィルタが定義されます。Model Armor のフロア設定を更新するときに、Model Armor がサニタイズ オペレーションをログに記録するかどうかを指定できます。

Agent Platform と Google および Google Cloud MCP サーバーのサニタイズ オペレーションのロギングは、個別に有効にできます。有効にすると、ログにはプロンプトとレスポンス（Agent Platform の場合）またはツール呼び出しとツール レスポンス（MCP サーバーの場合）、Model Armor の評価結果、追加のメタデータ フィールドが含まれます。

注: Google Cloud コンソールでは、Agent Platform のサニタイズ オペレーションのフロア設定ロギングはデフォルトで有効になっていますが、MCP サーバーではデフォルトで無効になっています。

データ所在地の要件がある場合は、次の手順で Cloud Logging を有効にする前に、ログを準拠した保存場所に転送するようにログシンクを構成する必要があります。ログシンクを構成すると、Model Armor が適切なリージョン バケットにログを保存するようになります。詳細については、ログをリージョン化するをご覧ください。

次の例は、Agent Platform と Google および Google Cloud MCP サーバーの両方でサニタイズ オペレーションのロギングを有効にする方法を示しています。

コンソール

1. Google Cloud コンソールで、[Model Armor] ページに移動します。

   [Model Armor] に移動

2. Model Armor を有効にしたプロジェクトが表示されていることを確認します。

3. [フロア設定] タブに移動します。

4. [ログ] セクションで、[Vertex AI] と [Google マネージド MCP] のチェックボックスをオンにして、各サービスのロギングを有効にします。

5. [保存] をクリックします。

gcloud

Agent Platform のロギングを有効にするには --enable-vertex-ai-cloud-logging フラグを使用し、Google と Google Cloud MCP サーバーのロギングを有効にするには --enable-google-mcp-server-cloud-logging フラグを使用します。ロギングを無効にするには、--no-enable-vertex-ai-cloud-logging フラグと --no-enable-google-mcp-server-cloud-logging フラグを使用します。

次のコマンド例では、Agent Platform と Google の両方の Google Cloud MCP サーバーでサニタイズ オペレーションのロギングを有効にします。

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

PROJECT_ID は、プロジェクトの ID に置き換えます。

REST

ロギングを有効にするには、UpdateFloorSetting メソッドで、Agent Platform の aiPlatformFloorSetting.enableCloudLogging を true に、Google と Google Cloud MCP サーバーの googleMcpServerFloorSetting.enableCloudLogging を true に設定します。

次のコマンド例では、Agent Platform と Google の両方の Google Cloud MCP サーバーでサニタイズ オペレーションのロギングを有効にします。

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

PROJECT_ID は、プロジェクトの ID に置き換えます。

Python

このコードを実行するには、まず Python 開発環境を設定し、Model Armor Python SDK をインストールします。

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

PROJECT_ID は、プロジェクトの ID に置き換えます。

Model Armor ログを表示してフィルタする

Model Armor ログを表示してフィルタするには、Logging のログ エクスプローラを使用します。

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

   詳細については、ログ エクスプローラを使用してログを表示するをご覧ください。

2. クエリペインに次のいずれかのクエリを入力して、Model Armor ログをフィルタします。

   • 監査ログやサニタイズ オペレーション ログなど、すべての Model Armor ログを表示するには:

     protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
     

   • Model Armor の監査ログのみを表示するには:

     protoPayload.serviceName="modelarmor.googleapis.com"
     

     すべてのサービス名とモニタリング対象リソースタイプの一覧については、モニタリング対象リソースとサービスをご覧ください。

   • サニタイズ オペレーションの Model Armor ログのみを表示するには:

     jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
     

     サニタイズ オペレーション ログをさらに絞り込むには、クエリでクライアント名または相関 ID を指定します。

     • クライアント名を使用する: Model Armor が Gemini Enterprise Agent Platform や Gemini Enterprise などのサービスと統合されている場合は、クライアント名を使用して特定の統合のログをフィルタできます。

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
       

     • 相関 ID を使用する場合:

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
       

     次のように置き換えます。

     • CLIENT_NAME: クライアントの名前。次のいずれかの値を使用します。
       • CLIENT_NAME_UNSPECIFIED: クライアント名が指定されていない場合に使用されるデフォルト値。
       • VERTEX_AI: Gemini Enterprise Agent Platform との統合用。
       • LOAD_BALANCER: ロードバランサをサービス拡張機能として使用する統合の場合。
       • LANGCHAIN: LangChain との統合用。
       • GEMINI_ENTERPRISE_BUSINESS: Gemini Enterprise - Business エディションとの統合用。
       • GOOGLE_MCP_SERVER: Google および Google が管理する MCP サーバーとの統合用。
       • AGENT_GATEWAY: Agent Gateway との統合用。
       • GEMINI_ENTERPRISE_NON_BUSINESS Gemini Enterprise エディション（Business 以外）との統合（Standard、Plus、Frontline）。
       • SECURE_WEB_PROXY Secure Web Proxy との統合用。
     • CORRELATION_ID: 特定のリクエストに対して生成する固有識別子。

ログと関連イベントを関連付ける

特定のインタラクションのログとイベントを関連付けるには、Model Armor クライアント相関 ID を使用します。この ID は、システム全体で特定のリクエストを追跡するために生成する固有識別子（UUID など）です。curl ヘッダーにクライアント相関 ID を設定するには、-H オプションを使用して、リクエストに MA-Client-Correlation-Id カスタム ヘッダーを含めます。

サンプル形式は次のとおりです。

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

次のように置き換えます。

• PROJECT_ID: テンプレートが属するプロジェクトの ID。
• LOCATION: テンプレートのロケーション。
• TEMPLATE_ID: テンプレートの ID。
• USER_PROMPT: モデルに提供されたプロンプト。
• MODEL_RESPONSE: モデルから受信したレスポンス。

プラットフォーム ログと Cloud Audit Logs

Model Armor テンプレートまたはフロア設定内で有効にできるログと Cloud Audit Logs を区別することが重要です。

機能	Cloud Audit Logs	プラットフォームのログ
主な目的	API 呼び出しのセキュリティ監査（誰がいつ何をしたか）とコンプライアンス モニタリング。	サニタイズ イベントの運用モニタリング、デバッグ、詳細な分析。
キャプチャされた API オペレーション	テンプレートとフロア設定に対する作成、読み取り、更新、削除、一覧取得のオペレーション。サニタイズ オペレーション（SanitizeUserPrompt、SanitizeModelResponse）はメタデータとしてログに記録されます。	SanitizeUserPrompt や SanitizeModelResponse などのすべてのリクエストをキャプチャします。
ペイロードの内容	サニタイズ オペレーションの実際のユーザー プロンプトまたはモデル レスポンス テキストは含まれません。呼び出し元、メソッド、リソース、タイムスタンプ、ステータスなどのメタデータが含まれます。	プロンプトやレスポンス テキスト、フィルタ結果、サニタイズのその他の詳細など、完全なペイロードが含まれます。
有効化メカニズム	Model Armor API の標準の Google Cloud IAM 監査ログ設定。データアクセス ログは、明示的に有効にする必要があることがよくあります。テンプレート オペレーションの監査ログは自動的に生成されます。	テンプレート メタデータまたはフロア設定でブール値フラグ log_sanitize_operations を設定することで有効になります。
ロギング条件	テンプレートとフロア設定に対する作成、読み取り、更新、削除、一覧取得のオペレーションを自動的にログに記録します。	Sensitive Data Protection が有効になっているかどうか、フィルタ設定が一致したかどうかに関係なく、データプレーン リクエストのログデータ（ユーザー プロンプトとモデル レスポンス）を記録します。
ログのボリュームと費用	一般的にサイズが小さく、予測可能性が高く、標準の Cloud Logging の料金が発生します。	非常に大きく、大量になる可能性があり、ペイロードが大きく頻繁に使用されるため、Cloud Logging の費用が高額になる可能性があります。大きなペイロードは複数のログエントリに分割されることがあります。
セキュリティ上の考慮事項	ペイロード データはログに記録されないため、比較的安全です。アクセスするには特別な IAM 権限が必要です（監査ログを表示するための特定の IAM ロールなど）。	センシティブなユーザーデータ（PII、機密情報）が含まれている。ログ表示権限（roles/logging.privateLogViewer など）を持つすべてのユーザーがアクセスできます。
推奨事項	一般的なセキュリティとコンプライアンスのモニタリングを有効にします。	アクセス制御されたシンク（厳格な IAM を使用した BigQuery など）に安全に転送されない限り、プロダクションやセンシティブ データにはおすすめしません。

テンプレートでロギングを有効にすると、未加工のプロンプトとレスポンスが Logging に書き込まれます。このデータには、ユーザーデータ、個人を特定できる情報（PII）、機密情報が含まれる可能性があります。トラフィックが多く、ペイロードが大きいと、ロギング費用が大幅に増加し、ログの量が上限を超えて慎重な管理が必要になる可能性があります。

監査ログの呼び出し元 ID

監査ログを表示すると、Cloud Audit Logs は呼び出し元の ID を protoPayload.authenticationInfo.principalEmail フィールドにキャプチャします。記録される ID は、Model Armor API の呼び出し方法によって異なります。

• API の直接呼び出し: ユーザーまたはサービス アカウントが Model Armor API を直接呼び出す場合（gcloud、クライアント ライブラリ、REST API などを使用）、principalEmail にはそのユーザーまたはサービス アカウントのメールアドレスが含まれます。
• 統合された Google Cloud サービスによる呼び出し: Model Armor が Gemini Enterprise Agent Platform などの別のGoogle Cloud サービスと統合されている場合、principalEmail にはそのサービスの ID（通常は Google が管理するサービス アカウント）が含まれます。サービス エージェントの形式は service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com です。たとえば、Gemini Enterprise Agent Platform 機能から発信された呼び出しでは、Gemini Enterprise Agent Platform サービス エージェントが使用されます。

呼び出し元を区別するには、監査ログエントリの principalEmail フィールドを調べます。エンドユーザーまたはユーザー管理のサービス アカウントからの呼び出しにはメールアドレスが表示されますが、他の Google Cloud サービスを介した呼び出しには Google 管理のサービス アカウントのメールアドレスが表示されます。