ロギングを構成する

このドキュメントでは、次のオペレーションをロギングするように 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 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

   API の有効化

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

gcloud

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

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

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

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

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

データ所在地の要件がある場合は、次の手順で 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

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

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

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: Load Balancer as a Service Extension を使用した統合の場合。
       • LANGCHAIN: LangChain との統合の場合。
       • GEMINI_ENTERPRISE_BUSINESS: Gemini Enterprise - Business エディションとの統合の場合。
       • GOOGLE_MCP_SERVER: Google と Google が管理する MCP サーバーとの統合の場合。
       • AGENT_GATEWAY: Agent Gateway との統合の場合。
       • GEMINI_ENTERPRISE_NON_BUSINESS : Business 以外の Gemini Enterprise エディション（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 が管理するサービス アカウントのメールアドレスが表示されます。