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 how logs are priced, see the Cloud Logging pricing page. Model Armor usage charges may also apply based on the volume of data processed; see Model Armor Pricing for details.

Before you begin

Complete these tasks before you complete the remaining tasks on this page.

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 Model Armor APIs 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.
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-managed Model Context Protocol (MCP) servers, set up traffic sanitization through floor settings. For more information, see Configure protection for Google and Google Cloud remote MCP servers. (Preview)

Configure logging in templates

Templates define the filters and thresholds for different safety and security categories. When creating or updating 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 enables logging of the create, update, read, and delete template operations.
log_sanitize_operations: A boolean value that enables logging of the sanitize operations. The logs include the prompt and response, Model Armor's evaluation results, and additional metadata fields.

Console

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

Go to Model Armor
Verify that you are viewing the project that you activated Model Armor on.
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

Floor settings establish baseline safety and security filters across all Gemini models in Vertex AI and Google-managed Model Context Protocol (MCP) servers (Preview) within your project. When updating Model Armor floor settings, you can specify whether Model Armor sanitize operations are logged.

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

Console

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

Go to Model Armor
Verify that you are viewing the project that you activated Model Armor on.
Navigate to the Floor Settings tab.
In the Logs section, select Google managed MCP.
Click Save.

gcloud

You can one of the following flags to manage sanitize operations logging in floor settings.

To enable Logging, use one of the following flags:

For Vertex AI, use the flag --enable-vertex-ai-cloud-logging.
For Google-managed MCP servers, use the flag --enable-google-mcp-server-cloud-logging.

To disable Logging, use one of the following flags:

For Vertex AI, use the flag --no-enable-vertex-ai-cloud-logging.
For Google-managed MCP servers, use the flag --no-enable-google-mcp-server-cloud-logging.

Note: You can enable or disable logging for one or both services using a single command.

The following example command enables sanitize operations logging for both Vertex AI and Google-managed 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

You can use the UpdateFloorSetting method to update the floor settings to enable sanitize operations logging. When you use this method, make sure to set the appropriate parameter to true to enable logging:

For Vertex AI, set aiPlatformFloorSetting.enableCloudLogging to true.
For Google-managed MCP servers, set googleMcpServerFloorSetting.enableCloudLogging to true.

The following example command enables sanitize operations logging for both Vertex AI and Google-managed 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 logs

To view Model Armor logs, you can use the Logs Explorer in Logging, follow these steps:

Navigate to the Logs Explorer in the Google Cloud console. For more information, see View logs by using the Logs Explorer.
Filter the logs by the service name modelarmor.googleapis.com.
Look for entries that are related to the operations that you enabled in your template. For a list of all the service names and monitored resource types, see Monitored resources and services.

Filter Model Armor logs

You can use log labels to filter the Model Armor logs for the sanitization operations and template logging. To do this, follow these instructions:

Run the following query in the Logs Explorer to filter the sanitization operations logs.

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

To further refine the sanitization operation logs, you can specify a project ID, client name, or correlation ID in the query.

Using a project ID:

jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID

Using a client name:

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

Using a correlation ID:

labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"

Replace the following:

PROJECT_ID: the Google Cloud project ID.
CLIENT_NAME: the name of your client.
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 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 custom header in your request.

Here's the sample format:

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.

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 up traffic sanitization

Configure logging in templates

Console

REST

Python

Configure logging in floor settings

Console

gcloud

REST

Python

View logs

Filter Model Armor logs

Correlate logs and related events

Configure logging