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 menyaring perintah pengguna atau respons model

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

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

Sebelum memulai

Sebelum memulai, selesaikan 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

Aktifkan Model Armor API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. 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 Google Cloud , aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah 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 dengan benar ke layanan Model Armor.

Jalankan perintah berikut untuk menetapkan endpoint API bagi 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 MCP Google dan Google Cloud , siapkan pembersihan traffic melalui setelan lantai. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi perlindungan untuk server Google dan Google Cloud MCP.

Mengonfigurasi logging dalam template

Template menentukan filter dan batas untuk berbagai kategori keamanan dan keselamatan. Saat membuat atau memperbarui template Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi tertentu. Gunakan tanda 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 dari perintah pengguna dan respons model selama operasi pembersihan.

Konsol

Di konsol Google Cloud , 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 ingin Anda konfigurasi logging-nya.
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 di setelan ruang

Saat Anda menerapkan setelan batas bawah pada traffic dari model Gemini di Platform Agen Gemini Enterprise dan server MCP Google dalam project Anda, setelan batas bawah menentukan filter keamanan dan keselamatan untuk operasi pembersihan. Google Cloud Saat memperbarui setelan batas bawah Model Armor, Anda dapat menentukan apakah operasi pembersihan log Model Armor dilakukan.

Anda dapat mengaktifkan logging operasi pembersihan untuk Agent Platform dan server Google Cloud MCP Google secara terpisah. Jika diaktifkan, log akan menyertakan perintah dan respons (untuk Platform Agen) 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 serta Google Cloud MCP.

Konsol

Di konsol Google Cloud , buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Buka tab Setelan Lantai.
Di bagian Logs, centang kotak Vertex AI dan MCP yang dikelola Google untuk mengaktifkan logging untuk setiap layanan.
Klik Simpan.

gcloud

Gunakan tanda --enable-vertex-ai-cloud-logging untuk mengaktifkan logging untuk Agent Platform, dan tanda --enable-google-mcp-server-cloud-logging untuk mengaktifkan logging untuk server MCP Google dan Google Cloud . Untuk menonaktifkan pencatatan log, 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 serta 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

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 serta 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 konsol Google Cloud , 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 sanitasi:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Untuk melihat hanya log audit Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Untuk mengetahui daftar semua nama layanan dan jenis resource yang dimonitor, lihat Resource dan layanan yang dimonitor.
- Untuk melihat hanya log Model Armor untuk operasi sanitasi:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Untuk lebih menyaring log operasi sanitasi, Anda dapat menentukan nama klien atau ID korelasi dalam kueri.
  - Menggunakan nama klien: Saat Model Armor terintegrasi dengan layanan seperti Platform Agen Gemini Enterprise 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 yang dikelola Google dan 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.

Menghubungkan 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 menyetel ID korelasi klien di header curl, gunakan opsi -H untuk menyertakan header kustom MA-Client-Correlation-Id dalam permintaan Anda.

Berikut contoh formatnya:

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 setelan minimum atau template Model Armor dan Cloud Audit Logs.

Fitur	Cloud Audit Logs	Log platform
Tujuan utama	Audit keamanan panggilan API (siapa yang melakukan apa, kapan) dan pemantauan kepatuhan.	Pemantauan operasional, proses debug, dan analisis mendetail tentang peristiwa pembersihan.
Operasi API yang direkam	Membuat, membaca, mengupdate, menghapus, dan mencantumkan operasi pada template dan setelan lantai. Operasi pembersihan (`SanitizeUserPrompt`, `SanitizeModelResponse`) dicatat sebagai metadata.	Mencatat semua permintaan seperti `SanitizeUserPrompt` dan `SanitizeModelResponse`.
Konten payload	Tidak menyertakan perintah pengguna atau teks respons model yang sebenarnya untuk operasi pembersihan. Berisi metadata seperti pemanggil, metode, resource, stempel waktu, dan status.	Mencakup payload lengkap, seperti teks perintah atau respons, hasil filter, dan detail sanitasi lainnya.
Mekanisme pengaktifan	Setelan log audit IAM standar untuk Model Armor API. Google Cloud Log akses data sering kali memerlukan pengaktifan eksplisit. Log audit untuk operasi template dibuat secara otomatis.	Diaktifkan dengan menyetel tanda boolean `log_sanitize_operations` di metadata template atau setelan lantai.
Kondisi logging	Log membuat, membaca, memperbarui, menghapus, dan mencantumkan operasi pada template dan setelan lantai secara otomatis.	Mencatat data (perintah pengguna dan respons model) untuk permintaan dataplane apa pun, terlepas dari apakah Sensitive Data Protection diaktifkan atau apakah ada setelan filter yang cocok.
Volume dan biaya log	Umumnya lebih kecil dan lebih dapat diprediksi, sehingga dikenai harga Cloud Logging standar.	Dapat berukuran sangat besar dan bervolume tinggi, yang 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 akses (misalnya, BigQuery dengan IAM yang ketat).

Mengaktifkan logging dalam template akan menulis perintah dan respons mentah ke Logging. Data ini mungkin mencakup data pengguna 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 di 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), maka principalEmail berisi alamat email pengguna atau akun layanan tersebut.
Pemanggilan melalui layanan Google Cloud terintegrasi: Jika Model Armor terintegrasi dengan layananGoogle Cloud lain seperti Platform Agen Gemini Enterprise, maka principalEmail berisi identitas layanan tersebut, yang biasanya merupakan akun layanan yang dikelola Google. 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 dalam entri log audit. Panggilan dari pengguna akhir atau akun layanan yang dikelola pengguna menampilkan alamat email mereka, sedangkan panggilan melalui layanan Google Cloud lainnya 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 di setelan ruang

Konsol

gcloud

REST

Python

Melihat dan memfilter log Model Armor

Menghubungkan log dan peristiwa terkait

Log platform versus Cloud Audit Logs

Identitas pemanggil di log audit

Mengonfigurasi logging