Configure logging

This document describes how to configure Model Armor to log the following operations:

Operations that create, update, or delete a template
Operations that sanitize a user prompt or model response

Model Armor uses audit logs to record administrative and resource management activities. For more information, see Model Armor audit logging.

For information about log pricing, see the Cloud Logging pricing. Model Armor usage charges might also apply based on the volume of data processed; see Model Armor Pricing for details.

Before you begin

Before you begin, complete the following tasks.

Obtain the required permissions

To get the permissions that you need to configure logging for Model Armor, ask your administrator to grant you the Model Armor Admin (roles/modelarmor.admin) IAM role on the Model Armor template. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Enable APIs

You must enable the Model Armor API before you can use Model Armor.

Console

Enable the Model Armor API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Select the project where you want to activate Model Armor.

gcloud

Before you begin, follow these steps using the Google Cloud CLI with the Model Armor API:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Set the API endpoint override using the gcloud CLI.

Set the API endpoint override using the gcloud CLI

This step is only required if you are using the gcloud CLI to enable the Model Armor API. You must manually set the API endpoint override to ensure the gcloud CLI correctly routes requests to the Model Armor service.

Run the following command to set the API endpoint for the Model Armor service.

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

Replace LOCATION with the region where you want to use Model Armor.

Set up traffic sanitization

For Google and Google Cloud MCP servers, set up traffic sanitization through floor settings. For more information, see Configure protection for Google and Google Cloud MCP servers.

Configure logging in templates

Templates define the filters and thresholds for different safety and security categories. When you create or update a Model Armor template, you can specify whether Model Armor logs certain operations. Use the following flags in the template metadata:

log_template_operations: A boolean value that lets you log the create, update, read, and delete template operations.
log_sanitize_operations: A boolean value that lets you log the full content of user prompts and model responses during sanitize operations.

Console

In the Google Cloud console, go to the Model Armor page.

Go to Model Armor
Verify that you are viewing the project for which you activated Model Armor.
On the Model Armor page, click Create Template. For more information about creating templates, see Create a Model Armor template.
In the Configure logging section, select the operations for which you want to configure logging.
Click Create.

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"

Replace the following:

PROJECT_ID: the ID of the project that the template belongs to.
LOCATION: the location of the template.
TEMPLATE_ID: the ID of the template.

Python

To run this code, first set up a Python development environment and install the 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)

Replace the following:

PROJECT_ID: the ID of the project that the template belongs to.
LOCATION: the location of the template.
TEMPLATE_ID: the ID of the template.

Configure logging in floor settings

When you enforce floor settings on traffic from Gemini models in Gemini Enterprise Agent Platform and Google and Google Cloud MCP servers within your project, floor settings define the safety and security filters for sanitization operations. When you are updating Model Armor floor settings, you can specify whether Model Armor logs sanitize operations.

You can enable logging of sanitize operations for Agent Platform and Google and Google Cloud MCP servers individually. When enabled, logs include the prompt and response (for Agent Platform) or tool calls and tool responses (for MCP servers), Model Armor's evaluation results, and additional metadata fields.

The following examples show how to enable sanitize operations logging for both Agent Platform and Google and Google Cloud MCP servers.

Console

In the Google Cloud console, go to the Model Armor page.

Go to Model Armor
Verify that you are viewing the project for which you activated Model Armor.
Navigate to the Floor Settings tab.
In the Logs section, select the Vertex AI and Google managed MCP checkboxes to enable logging for each service.
Click Save.

gcloud

Use the --enable-vertex-ai-cloud-logging flag to enable logging for Agent Platform, and the --enable-google-mcp-server-cloud-logging flag to enable logging for Google and Google Cloud MCP servers. To disable logging, use the --no-enable-vertex-ai-cloud-logging and --no-enable-google-mcp-server-cloud-logging flags.

The following example command enables sanitize operations logging for both Agent Platform and Google and Google Cloud MCP servers:

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

Replace PROJECT_ID with the ID of your project.

REST

To enable logging, set aiPlatformFloorSetting.enableCloudLogging to true for Agent Platform and googleMcpServerFloorSetting.enableCloudLogging to true for Google and Google Cloud MCP servers in the UpdateFloorSetting method.

The following example command enables sanitize operations logging for both Agent Platform and Google and Google Cloud MCP servers:

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"

Replace PROJECT_ID with the ID of your project.

Python

To run this code, first set up a Python development environment and install the 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}")

Replace PROJECT_ID with the ID of your project.

View and filter Model Armor logs

To view and filter Model Armor logs, use the Logs Explorer in Logging:

In the Google Cloud console, go to the Logs Explorer page.

Go to Logs Explorer

For more information, see View logs by using the Logs Explorer.
In the query pane, enter one of the following queries to filter Model Armor logs:
- To view all Model Armor logs, including audit logs and sanitization operation logs:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- To view only Model Armor audit logs:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  For a list of all the service names and monitored resource types, see Monitored resources and services.
- To view only Model Armor logs for sanitization operations:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  To further refine the sanitization operation logs, you can specify a client name or correlation ID in the query.
  - Using a client name: When Model Armor integrates with services like Gemini Enterprise Agent Platform or Gemini Enterprise, you can use the client name to filter logs for a specific integration.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Using a correlation ID:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  Replace the following:
  - CLIENT_NAME: the name of your client; for example, VERTEX_AI.
  - CORRELATION_ID: the unique identifier that you generate for a specific request.

Correlate logs and related events

To correlate logs and events for a specific interaction, you can use a Model Armor client correlation ID. This ID is a unique identifier that you generate (for example, a UUID) that tracks a specific request across your system. To set a client correlation ID in a curl header, use the -H option to include a MA-Client-Correlation-Id custom header in your request.

Here's the sample format:

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"

Replace the following:

PROJECT_ID: the ID of the project that the template belongs to.
LOCATION: the location of the template.
TEMPLATE_ID: the ID of the template.
USER_PROMPT: the prompt provided to the model.
MODEL_RESPONSE: the response received from the model.

Platform logs versus Cloud Audit Logs

It's important to distinguish between the logs that you can enable within a Model Armor template or floor settings and Cloud Audit Logs.

Feature	Cloud Audit Logs	Platform logs
Primary purpose	Security auditing of API calls (who did what, when) and compliance monitoring.	Operational monitoring, debugging, and detailed analysis of sanitization events.
API operations captured	Create, read, update, delete, and list operations on templates and floor settings. Sanitize operations (`SanitizeUserPrompt`, `SanitizeModelResponse`) are logged as metadata.	Captures all requests such as `SanitizeUserPrompt` and `SanitizeModelResponse`.
Payload content	Does not include the actual user prompt or model response text for sanitize operations. Contains metadata like the caller, method, resource, timestamp, and status.	Includes the full payload, such as the prompt or response text, filter results, and other details of the sanitization.
Enabling mechanism	Standard Google Cloud IAM audit logs settings for the Model Armor API. Data access logs often require explicit enablement. Audit logs for template operations are generated automatically.	Enabled by setting the boolean flag `log_sanitize_operations` in the template metadata or floor settings.
Logging conditions	Logs create, read, update, delete, and list operations on templates and floor settings automatically.	Logs data (user prompts and model responses) for any dataplane requests, regardless of whether Sensitive Data Protection is enabled or if any filter setting was matched.
Log volume and cost	Generally smaller and more predictable, incurring standard Cloud Logging pricing.	Can be very large and voluminous, potentially leading to significant Cloud Logging costs due to large payloads and frequent use. Large payloads might be split into multiple log entries.
Security considerations	Relatively safe as payload data is not logged. Requires special IAM permissions to access (for example, specific IAM roles to view audit logs).	Contains potentially sensitive user data (PII, confidential information). Accessible to anyone with log viewing permissions (for example, `roles/logging.privateLogViewer`).
Recommendation	Enable for general security and compliance monitoring.	Not recommended for production or sensitive data unless securely routed to an access-controlled sink (for example, BigQuery with strict IAM).

Enabling logging in a template writes raw prompts and responses to Logging. This data might include sensitive user data, personally identifiable information (PII), or confidential information. High traffic and large payloads can lead to substantial logging costs and potential for large log volumes exceeding limits and requiring careful management.

Caller identity in audit logs

When you view audit logs, Cloud Audit Logs captures the identity of the caller in the protoPayload.authenticationInfo.principalEmail field. The identity recorded depends on how the Model Armor API is called:

Direct API invocation: If a user or service account calls the Model Armor API directly (for example, by using gcloud, client libraries, or REST APIs), then principalEmail contains the email address of that user or service account.
Invocation through an integrated Google Cloud service: If Model Armor integrates with another Google Cloud service such as Gemini Enterprise Agent Platform, then principalEmail contains that service's identity, which is typically a Google-managed service account. The format for service agents is service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. For example, a call that originates from a Gemini Enterprise Agent Platform feature uses a Gemini Enterprise Agent Platform service agent.

To distinguish between callers, examine the principalEmail field in the audit log entry. Calls from end-users or user-managed service accounts show their email addresses, while calls through other Google Cloud services show Google-managed service account email addresses.

Configure logging Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Obtain the required permissions

Enable APIs

Console

gcloud

Set the API endpoint override using the gcloud CLI

Set up traffic sanitization

Configure logging in templates

Console

REST

Python

Configure logging in floor settings

Console

gcloud

REST

Python

View and filter Model Armor logs

Correlate logs and related events

Platform logs versus Cloud Audit Logs

Caller identity in audit logs

Configure logging