Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mengonfigurasi logging

Dokumen ini menjelaskan cara mengonfigurasi Model Armor untuk mencatat operasi berikut:

Operasi yang membuat, memperbarui, atau menghapus template
Operasi yang membersihkan perintah pengguna atau respons model

Model Armor menggunakan log audit untuk mencatat aktivitas pengelolaan resource dan administratif. Untuk mengetahui informasi selengkapnya, lihat Logging audit Model Armor.

Untuk mengetahui informasi tentang harga log, lihat Harga Cloud Logging harga. Biaya penggunaan Model Armor juga dapat berlaku berdasarkan volume data yang diproses; lihat Harga Model Armor untuk mengetahui detailnya.

Sebelum memulai

Sebelum memulai, selesaikan tugas-tugas berikut.

Mendapatkan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi logging untuk Model Armor, minta administrator untuk memberi Anda peran IAM Model Armor Admin (roles/modelarmor.admin) pada template Model Armor. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengaktifkan API

Anda harus mengaktifkan Model Armor API sebelum dapat menggunakan Model Armor.

Konsol

Mengaktifkan Model Armor API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
Mengaktifkan API
Pilih project tempat Anda ingin mengaktifkan Model Armor.

gcloud

Sebelum memulai, ikuti langkah-langkah berikut menggunakan Google Cloud CLI dengan Model Armor API:

Di konsol, aktifkan Cloud Shell. Google Cloud

Aktifkan Cloud Shell

Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.
Tetapkan penggantian endpoint API menggunakan gcloud CLI.

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Langkah ini hanya diperlukan jika Anda menggunakan gcloud CLI untuk mengaktifkan Model Armor API. Anda harus menetapkan penggantian endpoint API secara manual untuk memastikan gcloud CLI merutekan permintaan ke layanan Model Armor dengan benar.

Jalankan perintah berikut untuk menetapkan endpoint API untuk layanan Model Armor.

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

Ganti LOCATION dengan region tempat Anda ingin menggunakan Model Armor.

Menyiapkan pembersihan traffic

Untuk server Google dan Google Cloud MCP, siapkan pembersihan traffic melalui setelan tingkat. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi perlindungan untuk server Google dan Google Cloud MCP.

Mengonfigurasi logging dalam template

Template menentukan filter dan batasan untuk berbagai kategori keselamatan dan keamanan. Saat membuat atau memperbarui template Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi tertentu. Gunakan flag berikut dalam metadata template:

log_template_operations: Nilai boolean yang memungkinkan Anda mencatat operasi pembuatan, pembaruan, pembacaan, dan penghapusan template.
log_sanitize_operations: Nilai boolean yang memungkinkan Anda mencatat konten lengkap perintah pengguna dan respons model selama operasi pembersihan.

Konsol

Di Google Cloud konsol, buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Di halaman Model Armor, klik Create Template. Untuk mengetahui informasi selengkapnya tentang cara membuat template, lihat Membuat template Model Armor.
Di bagian Configure logging, pilih operasi yang logging-nya ingin Anda konfigurasi.
Klik 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"

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal 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)

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Mengonfigurasi logging dalam setelan tingkat

Saat Anda menerapkan setelan tingkat pada traffic dari model Gemini di Gemini Enterprise Agent Platform dan server Google dan Google Cloud MCP dalam project Anda, setelan tingkat akan menentukan filter keselamatan dan keamanan untuk operasi pembersihan. Saat memperbarui setelan tingkat Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi pembersihan.

Anda dapat mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google dan Google Cloud MCP secara terpisah. Jika diaktifkan, log akan menyertakan perintah dan respons (untuk Agent Platform) atau panggilan alat dan respons alat (untuk server MCP), hasil evaluasi Model Armor, dan kolom metadata tambahan.

Contoh berikut menunjukkan cara mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google dan Google Cloud MCP.

Konsol

Di Google Cloud konsol, buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Buka tab Floor Settings.
Di bagian Logs, centang kotak Vertex AI dan Google managed MCP untuk mengaktifkan logging untuk setiap layanan.
Klik Save.

gcloud

Gunakan flag --enable-vertex-ai-cloud-logging untuk mengaktifkan logging untuk Agent Platform, dan --enable-google-mcp-server-cloud-logging flag untuk mengaktifkan logging untuk server Google dan Google Cloud MCP. Untuk menonaktifkan logging, gunakan flag --no-enable-vertex-ai-cloud-logging dan --no-enable-google-mcp-server-cloud-logging.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google dan 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

Ganti PROJECT_ID dengan ID project Anda.

REST

Untuk mengaktifkan logging, tetapkan aiPlatformFloorSetting.enableCloudLogging ke true untuk Agent Platform dan googleMcpServerFloorSetting.enableCloudLogging ke true untuk server Google dan Google Cloud MCP dalam metode UpdateFloorSetting.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server Agent Platform dan Google dan 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"

Ganti PROJECT_ID dengan ID project Anda.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal 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}")

Ganti PROJECT_ID dengan ID project Anda.

Melihat dan memfilter log Model Armor

Untuk melihat dan memfilter log Model Armor, gunakan Logs Explorer di Logging:

Di Google Cloud konsol, buka halaman Logs Explorer.

Buka Logs Explorer

Untuk mengetahui informasi selengkapnya, lihat Melihat log menggunakan Logs Explorer.
Di panel kueri, masukkan salah satu kueri berikut untuk memfilter log Model Armor:
- Untuk melihat semua log Model Armor, termasuk log audit dan log operasi pembersihan:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Untuk melihat log audit Model Armor saja:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Untuk mengetahui daftar semua nama layanan dan jenis resource yang dimonitor, lihat Resource dan layanan yang dimonitor.
- Untuk melihat log Model Armor untuk operasi pembersihan saja:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Untuk lebih menyempurnakan log operasi pembersihan, Anda dapat menentukan nama klien atau ID korelasi dalam kueri.
  - Menggunakan nama klien: Saat Model Armor terintegrasi dengan layanan seperti Gemini Enterprise Agent Platform atau Gemini Enterprise, Anda dapat menggunakan nama klien untuk memfilter log untuk integrasi tertentu.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Menggunakan ID korelasi:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  Ganti kode berikut:
  - CLIENT_NAME: nama klien Anda. Gunakan salah satu nilai berikut:
    - CLIENT_NAME_UNSPECIFIED: Nilai default, digunakan saat nama klien tidak ditentukan.
    - VERTEX_AI: Untuk integrasi dengan Gemini Enterprise Agent Platform.
    - LOAD_BALANCER: Untuk integrasi menggunakan Load Balancer sebagai Ekstensi Layanan.
    - LANGCHAIN: Untuk integrasi dengan LangChain.
    - GEMINI_ENTERPRISE_BUSINESS: Untuk integrasi dengan Gemini Enterprise - Edisi Business.
    - GOOGLE_MCP_SERVER: Untuk integrasi dengan server MCP Google dan yang dikelola Google.
    - AGENT_GATEWAY: Untuk integrasi dengan Agent Gateway.
    - GEMINI_ENTERPRISE_NON_BUSINESS Untuk integrasi dengan edisi Gemini Enterprise selain Business (Standard, Plus, Frontline).
    - SECURE_WEB_PROXY Untuk integrasi dengan Secure Web Proxy.
  - CORRELATION_ID: ID unik yang Anda buat untuk permintaan tertentu.

Mengaitkan log dan peristiwa terkait

Untuk mengaitkan log dan peristiwa untuk interaksi tertentu, Anda dapat menggunakan ID korelasi klien Model Armor. ID ini adalah ID unik yang Anda buat (misalnya, UUID) yang melacak permintaan tertentu di seluruh sistem Anda. Untuk menetapkan ID korelasi klien di header curl, gunakan opsi -H untuk menyertakan header kustom MA-Client-Correlation-Id dalam permintaan Anda.

Berikut format contohnya:

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"

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.
USER_PROMPT: perintah yang diberikan ke model.
MODEL_RESPONSE: respons yang diterima dari model.

Log platform versus Cloud Audit Logs

Penting untuk membedakan antara log yang dapat Anda aktifkan dalam template Model Armor atau setelan tingkat dan Cloud Audit Logs.

Fitur	Cloud Audit Logs	Log platform
Tujuan utama	Audit keamanan panggilan API (siapa melakukan apa, kapan) dan pemantauan kepatuhan.	Pemantauan operasional, proses debug, dan analisis mendetail peristiwa pembersihan.
Operasi API yang dicatat	Operasi pembuatan, pembacaan, pembaruan, penghapusan, dan pencantuman pada template dan setelan batas. Operasi pembersihan (`SanitizeUserPrompt`, `SanitizeModelResponse`) dicatat sebagai metadata.	Mencatat semua permintaan seperti `SanitizeUserPrompt` dan `SanitizeModelResponse`.
Konten payload	Tidak menyertakan teks perintah pengguna atau respons model yang sebenarnya untuk operasi pembersihan. Berisi metadata seperti pemanggil, metode, resource, stempel waktu, dan status.	Menyertakan payload lengkap, seperti teks perintah atau respons, hasil filter, dan detail pembersihan lainnya.
Mekanisme pengaktifan	Setelan log audit Standard Google Cloud IAM untuk Model Armor API. Log akses data sering kali memerlukan pengaktifan eksplisit. Log audit untuk operasi template dibuat secara otomatis.	Diaktifkan dengan menetapkan flag boolean `log_sanitize_operations` dalam metadata template atau setelan tingkat.
Kondisi logging	Log mencatat operasi pembuatan, pembacaan, pembaruan, penghapusan, dan pencantuman pada template dan setelan tingkat secara otomatis.	Mencatat data (perintah pengguna dan respons model) untuk permintaan dataplane apa pun, terlepas dari apakah Sensitive Data Protection diaktifkan atau apakah setelan filter cocok.
Volume dan biaya log	Umumnya lebih kecil dan lebih mudah diprediksi, sehingga dikenakan harga Cloud Logging standar.	Dapat sangat besar dan banyak, sehingga berpotensi menyebabkan biaya Cloud Logging yang signifikan karena payload besar dan penggunaan yang sering. Payload besar dapat dibagi menjadi beberapa entri log.
Pertimbangan keamanan	Relatif aman karena data payload tidak dicatat. Memerlukan izin IAM khusus untuk mengakses (misalnya, peran IAM tertentu untuk melihat log audit).	Berisi data pengguna yang berpotensi sensitif (PII, informasi rahasia). Dapat diakses oleh siapa saja yang memiliki izin melihat log (misalnya, `roles/logging.privateLogViewer`).
Rekomendasi	Aktifkan untuk pemantauan keamanan dan kepatuhan umum.	Tidak direkomendasikan untuk data produksi atau sensitif kecuali jika dirutekan dengan aman ke sink yang dikontrol aksesnya (misalnya, BigQuery dengan IAM yang ketat).

Mengaktifkan logging dalam template akan menulis perintah dan respons mentah ke Logging. Data ini mungkin menyertakan data pengguna yang sensitif, informasi identitas pribadi (PII), atau informasi rahasia. Traffic tinggi dan payload besar dapat menyebabkan biaya logging yang besar dan potensi volume log besar yang melebihi batas dan memerlukan pengelolaan yang cermat.

Identitas pemanggil dalam log audit

Saat Anda melihat log audit, Cloud Audit Logs akan mencatat identitas pemanggil di kolom protoPayload.authenticationInfo.principalEmail. Identitas yang dicatat bergantung pada cara Model Armor API dipanggil:

Pemanggilan API langsung: Jika pengguna atau akun layanan memanggil Model Armor API secara langsung (misalnya, dengan menggunakan gcloud, library klien, atau REST API), principalEmail akan berisi alamat email pengguna atau akun layanan tersebut.
Pemanggilan melalui layanan terintegrasi Google Cloud : Jika Model Armor terintegrasi dengan layanan lain seperti Gemini Enterprise Agent Platform, maka principalEmail akan berisi identitas layanan tersebut, yang biasanya merupakan akun layanan yang dikelola Google .Google Cloud Format untuk agen layanan adalah service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Misalnya, panggilan yang berasal dari fitur Gemini Enterprise Agent Platform menggunakan agen layanan Gemini Enterprise Agent Platform.

Untuk membedakan pemanggil, periksa kolom principalEmail di entri log audit. Panggilan dari pengguna akhir atau akun layanan yang dikelola pengguna akan menampilkan alamat email mereka, sedangkan panggilan melalui layanan lain Google Cloud akan menampilkan alamat email akun layanan yang dikelola Google.

Mengonfigurasi logging Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mendapatkan izin yang diperlukan

Mengaktifkan API

Konsol

gcloud

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Menyiapkan pembersihan traffic

Mengonfigurasi logging dalam template

Konsol

REST

Python

Mengonfigurasi logging dalam setelan tingkat

Konsol

gcloud

REST

Python

Melihat dan memfilter log Model Armor

Mengaitkan log dan peristiwa terkait

Log platform versus Cloud Audit Logs

Identitas pemanggil dalam log audit

Mengonfigurasi logging