Memantau agen

Halaman ini menjelaskan cara menggunakan metrik bawaan, metrik kustom, dan pemberitahuan untuk memantau agen Anda di Vertex AI Agent Engine.

Ringkasan

Anda dapat menggunakan Vertex AI Agent Engine menggunakan Cloud Monitoring tanpa penyiapan atau konfigurasi tambahan. Metrik agen bawaan dikumpulkan dan divisualisasikan secara otomatis di halaman Cloud Monitoring di konsolGoogle Cloud .

Metrik bawaan yang didukung

Metrik agen berikut didukung dan dikaitkan dengan resource yang dipantau Vertex AI Agent Engine aiplatform.googleapis.com/ReasoningEngine:

• Jumlah permintaan
• Latensi permintaan
• Waktu alokasi CPU container
• Waktu alokasi memori container

Lihat daftar lengkap metrik AI Platform untuk mengetahui detail selengkapnya tentang jenis metrik, unit, label, serta latensi dan periode pengambilan sampel.

Melihat metrik untuk agen

Anda dapat melihat metrik bawaan agen di konsol Google Cloud menggunakan Metrics Explorer:

1. Untuk mendapatkan izin melihat metrik di Metrics Explorer, minta administrator untuk memberi Anda peran Monitoring Viewer (roles/monitoring.viewer) di project Anda.

2. Buka Metrics Explorer di konsol Google Cloud :

   Buka Metrics Explorer

3. Pilih Google Cloud project Anda.

4. Klik Pilih metrik untuk membuka kotak penelusuran.

5. Masukkan Vertex AI Reasoning Engine di kotak penelusuran, lalu klik Vertex AI Reasoning Engine.

6. Klik kategori metrik Reasoning_engine, lalu klik metrik, seperti Request count.

7. Secara opsional, tetapkan filter label tambahan, elemen agregasi, dan sesuaikan rentang waktu.

Secara default, diagram di Metrics Explorer untuk metrik Jumlah permintaan menyelaraskan titik data dengan interval waktu default dan memetakan titik data sebagai permintaan per detik (metrik kecepatan).

Catatan: Label dikategorikan sebagai label resource (umum untuk semua metrik, seperti resource_container, location, reasoning_engine_id) atau label metrik (khusus untuk setiap metrik, seperti response_code untuk metrik Jumlah Permintaan). Lihat Komponen model metrik untuk mengetahui informasi selengkapnya tentang label.

Metrik kueri untuk agen

Anda juga dapat membuat kueri metrik melalui Prometheus Query Language (PromQL) atau Cloud Monitoring v3 API. PromQL menawarkan lebih banyak opsi untuk pemfilteran, agregasi, dan transformasi metrik, sementara Cloud Monitoring API memungkinkan Anda mencantumkan dan mengkueri semua titik data mentah secara terprogram.

Mengueri metrik dengan PromQL

Anda dapat menggunakan PromQL untuk menyelaraskan dan menggabungkan titik data dengan interval waktu kustom dan memetakan titik data yang diubah sebagai jumlah permintaan absolut (bukan permintaan per detik). Contoh berikut memfilter data menurut ID instance Agent Engine (RESOURCE_ID) dan kode respons (RESPONSE_CODE):

Catatan: Dalam kueri PromQL untuk Metrics Explorer, interval waktu default diwakili oleh ${__interval}, dan dikonfigurasi secara otomatis berdasarkan rentang waktu. Nilai ${__interval} sebanding dengan rentang waktu yang dipilih. Jika Anda membuat kueri metrik untuk jangka waktu yang lebih lama, nilai ${__interval} akan dikonfigurasi secara dinamis untuk nilai yang lebih besar. Lihat Penyelarasan: regularisasi dalam deret untuk mengetahui detail selengkapnya tentang penyelarasan deret waktu.

sum_over_time(
  increase(
      aiplatform_googleapis_com:reasoning_engine_request_count{
          monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
          reasoning_engine_id='RESOURCE_ID',
          response_code='RESPONSE_CODE'
      }
      [10m]
  )
  [10m:10m]
)

Anda dapat membuat kueri rasio error dengan menghitung rasio permintaan yang diberi label dengan kode respons error tertentu (seperti 500) terhadap jumlah total permintaan (persentase permintaan yang gagal):

sum_over_time(
  sum(
    rate(
      aiplatform_googleapis_com:reasoning_engine_request_count{
        monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
        reasoning_engine_id='RESOURCE_ID',
        response_code='500'
      }
      [10m]
    )
  )
  [10m:10m]
)
/
sum_over_time(
  sum(
    rate(
      aiplatform_googleapis_com:reasoning_engine_request_count{
        monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
        reasoning_engine_id='RESOURCE_ID',
      }
      [10m]
    )
  )
  [10m:10m]
)

Untuk mengetahui praktik terbaik dan batasan metrik rasio, lihat Tentang rasio metrik. Untuk contoh cara menyetel pemberitahuan untuk metrik rasio error, lihat Contoh kebijakan dalam JSON.

Membuat kueri metrik dengan Cloud Monitoring API

Anda dapat menggunakan Cloud Monitoring API untuk melakukan hal berikut:

• Mendapatkan definisi resource yang dipantau Vertex AI Agent Engine

• Mencantumkan definisi metrik agen yang tersedia

• Membuat kueri data deret waktu untuk request_count

Semua metrik Agen dikaitkan dengan resource yang dipantau aiplatform.googleapis.com/ReasoningEngine Agent Engine.

Anda dapat memanggil API ini melalui APIs Explorer, library klien khusus bahasa, atau command line. Lihat dokumentasi untuk membaca metrik melalui API Explorer dan library klien. Contoh berikut menunjukkan penggunaan di command line, khususnya alat curl.

Tips: Anda harus mengautentikasi permintaan saat memanggil API dengan curl. Lihat Melakukan autentikasi untuk menggunakan REST untuk mengetahui detail selengkapnya. Alias shell ini mungkin berguna: $ alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'.

Mendapatkan definisi resource yang dipantau Agent Engine

Perintah berikut mengambil definisi resource yang dipantau menggunakan projects.monitoredResourceDescriptors, serta semua label yang tersedia yang dapat digunakan untuk pemfilteran:

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/ReasoningEngine

Label harus menyertakan resource_container, location, dan reasoning_engine_id.

Mencantumkan definisi metrik agen yang tersedia

Perintah berikut menggunakan projects.metricDescriptors untuk mengambil semua metrik dan filter label untuk Agent Engine:

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/metricDescriptors?filter='metric.type=starts_with("aiplatform.googleapis.com/reasoning_engine")'

Hasilnya harus menyertakan definisi untuk metrik berikut serta label spesifiknya:

• aiplatform.googleapis.com/reasoning_engine/request_count
• aiplatform.googleapis.com/reasoning_engine/request_latencies
• aiplatform.googleapis.com/reasoning_engine/cpu/allocation_time
• aiplatform.googleapis.com/reasoning_engine/memory/allocation_time

Membuat kueri data deret waktu untuk request_count

Anda dapat menggunakan projects.timeSeries.list bersama dengan parameter seperti interval, filter, dan aggregation untuk membuat kueri data deret waktu.

Contoh berikut menunjukkan cara membuat kueri titik data mentah untuk metrik request_count untuk instance agen tertentu selama jangka waktu tertentu:

Catatan: Karakter tertentu harus dienkode URL.

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/timeSeries?filter='metric.type="aiplatform.googleapis.com/reasoning_engine/request_count"%20AND%20resource.labels.reasoning_engine_id="RESOURCE_ID"&interval.endTime=2025-03-26T11:00:0.0-08:00&interval.startTime=2025-03-26T10:00:0.0-08:00'

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• RESOURCE_ID: ID instance Agent Engine. Hal ini tidak selalu diperlukan. Anda dapat membuat kueri di beberapa instance Agent Engine dalam project yang sama.
• interval.startTime dan interval.endTime: Awal (inklusif) dan akhir (eksklusif) interval waktu, dalam format RFC 3339. Misalnya, "2025-03-26T11:22:33Z" untuk Coordinated Universal Time (UTC) dan "2025-03-26T11:22:33-08:00" untuk Pacific Standard Time (PST). Lihat definisi lengkap dan contoh lainnya di RFC 3339.

Anda akan melihat respons seperti berikut:

{
  "timeSeries": [
    {
      "metric": {
        "labels": {
          "response_code": "200",
          "response_code_class": "2xx"
        },
        "type": "aiplatform.googleapis.com/reasoning_engine/request_count"
      },
      "resource": {
        "type": "aiplatform.googleapis.com/ReasoningEngine",
        "labels": {
          "reasoning_engine_id": "RESOURCE_ID",
          "location": "LOCATION",
          "project_id": "PROJECT_ID"
        }
      },
      "metricKind": "DELTA",
      "valueType": "INT64",
      "points": [
        {
          "interval": {
            "startTime": "2025-03-26T18:55:27.001Z",
            "endTime": "2025-03-26T18:56:27Z"
          },
          "value": {
            "int64Value": "25"
          }
        },
        {
          "interval": {
            "startTime": "2025-03-26T18:54:27.001Z",
            "endTime": "2025-03-26T18:55:27Z"
          },
          "value": {
            "int64Value": "36"
          }
        }
        // ... more data points ...
      ]
    }
    // ... potentially more time series with other response codes ...
  ],
  "unit": "1"
}

Lihat projects.timeSeries.list untuk mengetahui detail selengkapnya tentang format respons.

Membuat metrik kustom untuk agen

Jika metrik agen bawaan tidak mencakup kasus penggunaan spesifik Anda, Anda dapat menentukan metrik kustom. Anda dapat membuat metrik kustom menggunakan metode berikut:

• Metrik berbasis log: Amati tren dan pola dalam volume besar entri log.

• Metrik yang ditentukan pengguna: Metrik yang tidak ditentukan oleh Google Cloud, seperti pengambilan data khusus aplikasi atau data sistem sisi klien.

Metrik berbasis log

Langkah-langkah berikut menunjukkan cara membuat dan menggunakan metrik berbasis log (tool_calling_count) untuk contoh alur kerja saat beberapa agen memanggil beberapa alat, dan Anda ingin menghitung pemanggilan alat:

1. Tentukan alat Anda untuk menulis entri log setiap kali alat tersebut dipanggil. Misalnya, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

2. Buat metrik berbasis log jenis penghitung baru melalui konsol Google Cloud :

   1. Buka halaman Log-based Metrics di konsol Google Cloud :

      Buka Log-based Metrics

   2. Di bagian Metrik buatan pengguna, klik Buat metrik. Panel Create log-based metric akan muncul.

   3. Untuk Jenis metrik, pilih Penghitung

   4. Untuk bagian Details, masukkan Log-based metric name. Contohnya, tool_calling_count. Secara opsional, masukkan Deskripsi dan Unit.

   5. Untuk bagian Filter selection, lakukan tindakan berikut:

      1. Di menu drop-down Pilih project atau bucket log, pilih Project logs

      2. Di kolom Build filter, masukkan filter log menggunakan bahasa kueri logging. Contoh:

         resource.type="aiplatform.googleapis.com/ReasoningEngine"
         resource.labels.reasoning_engine_id="RESOURCE_ID"
         textPayload =~ "tool-\d+ invoked by agent-\d+" -- assuming both tool and agent IDs are numeric
         

   6. Untuk bagian Labels, tambahkan dua label baru dengan mengklik tombol Add label.

      1. Untuk label pertama, lakukan hal berikut:

         1. Di kolom Nama label, masukkan tool.

         2. Di kolom Nama kolom, masukkan textPayload.

         3. Di kolom Regular expression, masukkan (tool-\d+) invoked by agent-\d+.

      2. Untuk label kedua, lakukan hal berikut:

         1. Di kolom Nama label, masukkan agent.

         2. Di kolom Nama kolom, masukkan textPayload.

         3. Di kolom Regular expression, masukkan tool-\d+ invoked by (agent-\d+).

      Tips: Jika log pemanggilan alat tersebut sudah tersedia di project, klik Pratinjau untuk menguji ekspresi reguler untuk tool dan agent.
      1. Klik Selesai.

   7. Klik Create metric.

3. Untuk melihat metrik tool_calling_count dan log terkaitnya, lakukan langkah-langkah berikut di konsol Google Cloud :

   1. Buka halaman Metrics Explorer di konsol Google Cloud :

      Buka Metrics Explorer

   2. Klik Pilih metrik untuk membuka kotak penelusuran.

   3. Masukkan Vertex AI Reasoning Engine di kotak penelusuran, lalu klik Vertex AI Reasoning Engine.

   4. Klik kategori metrik Metrik berbasis log, lalu klik Logging/user/tool_calling_count. Sesuaikan rentang waktu jika perlu.

   5. (Opsional) Filter menurut label tool dan agent.

      • Untuk mendapatkan jumlah pemanggilan total untuk alat tertentu bagi semua agen, tetapkan label filter tool dengan nilai ID alat tersebut.

      • Untuk mendapatkan jumlah pemanggilan total untuk agen tertentu untuk semua alat, tetapkan label filter agent dengan nilai ID agen tersebut.

      Secara opsional, tetapkan Sum By ke tool atau agent untuk mendapatkan total jumlah yang dikelompokkan menurut alat atau agen yang berbeda.

Catatan: Metrik berbasis log baru dikaitkan dengan resource yang dipantau agen yang sama aiplatform.googleapis.com/ReasoningEngine, sehingga Anda dapat mengandalkan label seperti reasoning_engine_id untuk pemfilteran dan penggabungan.

Lihat Mencatat log agen untuk mengetahui petunjuk tentang cara menulis log agen, dan Ringkasan metrik berbasis log untuk mengetahui detail selengkapnya tentang metrik berbasis log.

Metrik buatan pengguna

Langkah-langkah berikut menunjukkan cara membuat dan menggunakan metrik yang ditentukan pengguna (token_count) untuk contoh alur kerja saat beberapa agen memanggil beberapa model, dan Anda ingin menghitung jumlah total token yang digunakan (dengan asumsi bahwa Anda melacak jumlah token sejak aplikasi dimulai untuk setiap agen pemanggil dan model target):

1. Tentukan jenis metrik kustom dengan memanggil projects.metricDescriptors.create dengan parameter berikut:

   • name: string URL, seperti projects/PROJECT_ID

   • Request body: objek MetricDescriptor:

     {
       "name": "token_count",
       "description": "Token Consumed by models.",
       "displayName": "Token Count",
       "type": "custom.googleapis.com/token_count",
       "metricKind": "CUMULATIVE",
       "valueType": "INT64",
       "unit": "1",
       "labels": [
         {
           "key": "model",
           "valueType": "STRING",
           "description": "Model."
         },
         {
           "key": "agent",
           "valueType": "STRING",
           "description": "Agent."
         }
       ],
       "monitoredResourceTypes": [
         "generic_node"
       ]
     }
     

     Metrik baru token_count dibuat dengan jenis Cumulative, yang menampilkan jumlah total token sejak aplikasi dimulai. Lihat Jenis dan jenis metrik untuk mengetahui detail selengkapnya tentang metrik Cumulative. Label model dan agent mewakili nama model bahasa besar (LLM) target dan agen pemanggilan.

   1. Anda dapat menemukan metrik token_count di Metrics Explorer:

      1. Buka halaman Metrics Explorer di konsol Google Cloud :

      Buka Metrics Explorer

      1. Klik Pilih metrik untuk membuka kotak penelusuran.

      2. Masukkan Generic node di kotak penelusuran, lalu klik Metrik kustom.

      3. Klik Token Count.

   Catatan: Langkah ini hanya perlu dilakukan sekali.

2. Tulis titik data ke metrik baru dengan memanggil projects.timeSeries.create dengan parameter berikut:

   • name: string URL, seperti projects/PROJECT_ID

   • Request body: daftar objek TimeSeries:

     {
       "timeSeries": [
         {
           "metric": {
             "type": "custom.googleapis.com/token_count",
             "labels": {
               "model": "model-1",
               "agent": "agent-1"
             }
           },
           "resource": {
             "type": "generic_node",
             "labels": {
               "project_id": "PROJECT_ID",
               "node_id": "RESOURCE_ID",
               "namespace": "",
               "location": "us-central1"
             }
           },
           "points": [
             {
               "interval": {
                 "startTime": "2025-03-26T10:00:00-08:00",
                 "endTime": "2025-03-26T10:01:00-08:00"
               },
               "value": {
                 "int64Value": 15
               }
             }
           ]
         },
         {
           "metric": {
             "type": "custom.googleapis.com/token_count",
             "labels": {
               "model": "model-1",
               "agent": "agent-2"
             }
           },
           "resource": {
             "type": "generic_node",
             "labels": {
               "project_id": "PROJECT_ID",
               "node_id": "RESOURCE_ID",
               "namespace": "",
               "location": "us-central1"
             }
           },
           "points": [
             {
               "interval": {
                 "startTime": "2025-03-26T10:00:00-08:00",
                 "endTime": "2025-03-26T10:01:00-08:00"
               },
               "value": {
                 "int64Value": 20
               }
             }
           ]
         }
         // ... more time series ...
       ]
     }
     

     Catatan: Setiap kombinasi nilai label membentuk deret waktu, yang harus dilaporkan satu per satu dalam permintaan projects.timeSeries.create. Langkah ini perlu dilakukan secara berkala dari kode Anda. Jumlah value tidak akan berkurang hingga direset ke nol saat aplikasi dimulai ulang. Lihat metrik CUMULATIVE di TimeInterval untuk mengetahui persyaratan khusus pada startTime dan endTime.

3. Setelah titik data diupload melalui Cloud Monitoring API, Anda dapat melihat metrik baru token_count melalui konsol Google Cloud :

   1. Buka halaman Metrics Explorer di konsol Google Cloud :

      Buka Metrics Explorer

   2. Klik Pilih metrik untuk membuka kotak penelusuran.

   3. Masukkan Generic node di kotak penelusuran, lalu klik Metrik kustom.

   4. Klik Token Count. Sesuaikan rentang waktu dan konfigurasikan nilai label untuk model atau agent jika perlu.

Catatan: Metrik yang ditentukan pengguna baru tidak dikaitkan dengan resource yang dipantau Agent Engine aiplatform.googleapis.com/ReasoningEngine. Lihat Ringkasan metrik yang ditentukan pengguna untuk mendapatkan panduan selengkapnya tentang cara membuat dan menggunakan metrik yang ditentukan pengguna.

Membuat pemberitahuan untuk agen

Anda dapat menggunakan metrik bersama dengan pemberitahuan. Lihat Ringkasan pemberitahuan untuk mengetahui detail selengkapnya.

Contoh berikut menunjukkan cara membuat pemberitahuan batas untuk metrik request_latencies sehingga Anda menerima notifikasi saat latensi melampaui nilai yang telah ditentukan selama durasi tertentu:

1. Buka halaman Alerting di konsol Google Cloud :

   Buka Pemberitahuan

2. Klik Create Policy. Halaman Buat kebijakan pemberitahuan akan terbuka.

   1. Untuk Policy configuration mode, pilih Builder.

   2. Di menu drop-down Select a metric, pilih Vertex AI Reasoning Engine -> reasoning_engine -> Request Latency.

   3. Di bagian Tambahkan filter, opsionalnya konfigurasi filter (seperti reasoning_engine_id, response_code).

   4. Di bagian Transform data, alihkan Rolling window dan Rolling window function ke nilai seperti 5min dan 99th percentile (pantau persentil ke-99 latensi permintaan selama periode perataan 5 menit).

   5. Klik Berikutnya.

3. Di bagian Konfigurasi pemicu pemberitahuan, lakukan hal berikut:

   1. Pilih Batas untuk Jenis Kondisi.

   2. Pilih Pemicu pemberitahuan, seperti Deret waktu mana pun melanggar.

   3. Pilih Posisi batas, seperti Di atas batas.

   4. Masukkan nilai minimum, seperti 5000ms.

   5. Klik Berikutnya.

4. Di bagian Konfigurasi notifikasi dan finalisasi pemberitahuan, lakukan hal berikut:

   1. Pilih satu atau beberapa saluran notifikasi. Lihat bagian Mengelola saluran notifikasi untuk mengetahui detail selengkapnya.

   2. (Opsional) Konfigurasi subjek notifikasi, durasi penutupan otomatis insiden, label aplikasi, label kebijakan, tingkat keparahan, dan dokumentasi tambahan.

   3. Tetapkan nama kebijakan di bagian Name the alert policy, seperti latency-99p-alert.

   4. Klik Create policy.

Jika terjadi insiden, lihat Insiden untuk kebijakan pemberitahuan berbasis metrik untuk mengetahui informasi selengkapnya tentang cara mengonfirmasi dan menyelidiki insiden serta membisukan pemberitahuan.

Anda dapat menemukan contoh pemberitahuan lainnya di Contoh kebijakan dalam JSON.

Memantau metrik untuk agen

Anda dapat menggunakan dasbor Ringkasan Vertex AI Agent Engine untuk memantau kondisi operasional dan performa agen Anda.

Melihat dasbor default

1. Buka halaman Dashboards di konsol Google Cloud :

   Buka Dasbor

2. Pilih project Google Cloud Anda.

3. Di panel Dasbor Saya, tambahkan filter Name:Vertex AI Agent Engine Overview.

4. Klik Vertex AI Agent Engine Overview untuk menampilkan dasbor agen default.

Menyesuaikan dasbor default

Dasbor default hanya berisi metrik bawaan agen. Untuk menambahkan metrik kustom Anda sendiri ke dasbor, gunakan langkah-langkah berikut untuk menyalin dan menyesuaikan dasbor default:

1. Buka dasbor default.

2. Klik Salin Dasbor. Dalam dialog Salin Dasbor, klik Salin. Salinan dasbor akan terbuka. Anda juga dapat menemukan salinan dasbor di panel Dasbor Saya dalam kategori Kustom.

3. Di salinan dasbor, ikuti langkah-langkah berikut untuk menambahkan metrik:

   1. Klik Add widget. Panel samping Tambahkan widget akan muncul.

   2. Untuk Data, pilih Metrik. Panel samping Konfigurasi widget akan muncul.

   3. Klik Pilih metrik untuk membuka kotak penelusuran.

   4. Jika metrik kustom Anda dibuat menggunakan metrik berbasis log:

      1. Masukkan Vertex AI Reasoning Engine di kotak penelusuran, lalu klik Vertex AI Reasoning Engine.

      2. Klik kategori metrik Metrik berbasis log, lalu klik metrik, seperti Logging/user/tool_calling_count.

      3. Klik Terapkan.

   5. Jika metrik kustom Anda dibuat menggunakan metrik yang ditentukan pengguna:

      1. Masukkan Generic Node di kotak penelusuran, lalu klik Generic Node.

      2. Klik kategori metrik Metrik kustom, lalu klik metrik, seperti Jumlah Token.

      3. Klik Terapkan.

   6. Diagram baru yang menampilkan metrik kustom Anda akan muncul di dasbor.

4. Anda dapat menyesuaikan tata letak dasbor lebih lanjut, misalnya:

   1. Pindahkan widget dengan menahan judul widget dan menariknya ke lokasi lain di dasbor yang sama.

   2. Ubah ukuran widget Anda dengan menahan pojok kanan bawah widget dan menyesuaikan ukurannya.

Lihat Menambahkan diagram dan tabel ke dasbor kustom untuk mengetahui detail selengkapnya tentang cara menambahkan diagram metrik menggunakan Prometheus Query Language (PromQL), serta membuat tabulasi metrik Anda.

Jika Anda telah mengonfigurasi pemberitahuan kustom, lihat Menampilkan kebijakan pemberitahuan dan pemberitahuan di dasbor untuk menambahkan pemberitahuan tersebut ke dasbor Anda.