Mencatat aktivitas agen

Untuk menggunakan Cloud Logging di agen saat di-deploy ke Vertex AI Agent Engine Runtime, gunakan salah satu metode berikut:

• stdout / stderr: secara default (tanpa penyiapan tambahan), log yang ditulis ke stdout dan stderr akan dirutekan ke ID log reasoning_engine_stdout dan reasoning_engine_stderr. Batasannya adalah bahwa kolom tersebut harus berupa teks.
• Logging Python: logger Python bawaan dapat diintegrasikan dengan Cloud Logging. Dibandingkan dengan menulis ke stdout atau stderr, cara ini mendukung log terstruktur dan memerlukan penyiapan minimal.
• Klien Cloud Logging: pengguna dapat menulis log terstruktur, dan memiliki kontrol penuh atas logger (misalnya, menyetel logName dan jenis resource).

Catatan: Cloud Logging tidak didukung untuk subresource Vertex AI Agent Engine, seperti Sesi, Bank Memori, Eksekusi Kode, dan Example Store.

Menulis log untuk agen

Saat menulis log untuk agen, tentukan hal berikut:

• severity: Misalnya, info, warn, error
• payload: isi log (misalnya, teks atau JSON)
• kolom tambahan: untuk mengorelasikan log (misalnya, trace/span, tag, label)

Misalnya, untuk mencatat input setiap kueri saat mengembangkan agen:

stdout atau stderr

from typing import Dict

class MyAgent:

    def set_up(self):
        # No set up required. The logs from stdout and stderr are routed to
        # `reasoning_engine_stdout` and `reasoning_engine_stderr` respectively.
        pass

    def query(self, input: Dict):
        import sys

        print(
            f"input: {input}",
            file=sys.stdout,  # or sys.stderr
        )

Logging Python

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logging_client.setup_logging(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        import logging
        import json

        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        logging.info( # or .warning(), .error()
            json.dumps(input),
            extra=logging_extras,
        )

Klien Cloud Logging

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logger = self.logging_client.logger(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        self.logger.log_struct(
            input,
            severity="INFO",  # or "DEBUG", "WARNING", "ERROR", "CRITICAL"
            **logging_extras,
        )

Saat di-deploy dan dikueri, agen akan membuat entri log. Misalnya, kode

remote_agent = agent_engines.create(
    MyAgent(),
    requirements=["cloudpickle==3", "google-cloud-logging"],
)

remote_agent.query(input={"hello": "world"})

menghasilkan entri log yang mirip dengan berikut ini:

stdout atau stderr

{
  "insertId": "67a3bb3b000cc2df444361ab",
  "textPayload": "input: {'hello': 'world'}",
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID"
    }
  },
  "timestamp": "2025-02-05T19:25:47.836319Z",
  "logName": "projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout",  # or `*_stderr`
  "receiveTimestamp": "2025-02-05T19:25:47.842550772Z"
}

Logging Python

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-02-05T20:30:19.348067Z",
  "severity": "INFO",
  "labels": {
    "foo": "bar",
    "python_logger": "root",
  },
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Klien Cloud Logging

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-01-30T21:38:50.776813191Z",
  "severity": "INFO",
  "labels": {"foo": "bar"},
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Melihat log untuk agen

Anda dapat melihat entri log menggunakan Logs Explorer:

1. Untuk mendapatkan izin melihat log di Logs Explorer, minta administrator untuk memberi Anda peran Logs Viewer (roles/logging.viewer) di project Anda.

2. Buka Logs Explorer di konsol Google Cloud :

   Buka Logs Explorer

3. Pilih project Google Cloud Anda (yang sesuai dengan PROJECT_ID) di bagian atas halaman.

4. Di Resource Type, pilih Vertex AI Agent Builder Reasoning Engine.

Untuk agen berbasis Agent Development Kit, Anda juga dapat melihat log agen di Google Cloud konsol menggunakan dasbor Vertex AI Agent Engine.

Kueri runtime

Anda dapat memfilter log di Cloud Logging berdasarkan setiap operasi yang didukung dari agen yang di-deploy. Untuk melakukannya, filter log berdasarkan endpoint REST pokok untuk setiap kueri operasi:

• POST /api/reasoning_engine: Untuk kueri yang dibuat ke metode sinkron dan asinkron.
• POST /api/stream_reasoning_engine: Untuk kueri yang dibuat ke metode streaming dan streaming asinkron.
• POST /api/bidi_reasoning_engine: Untuk kueri yang dibuat ke metode streaming dua arah.

Kueri runtime dirutekan ke endpoint REST, bergantung pada kolom api_mode dalam daftar operasi yang didukung dari agen yang di-deploy.

Membuat kueri

Anda dapat menggunakan Logs Explorer untuk membuat kueri secara inkremental. Kueri biasanya dibuat berdasarkan pertimbangan berikut:

• timeline: untuk menelusuri entri log yang relevan berdasarkan waktu
• scope: untuk menelusuri entri log yang relevan berdasarkan atribut kanonis
  • resource: pisahkan dari jenis resource lain dalam project Anda.
    • type: muncul sebagai "Vertex AI Agent Builder Reasoning Engine" di Logs Explorer dan "aiplatform.googleapis.com/ReasoningEngine" dalam entri log.
    • labels: untuk lokasi (LOCATION), project PROJECT_ID, dan resource RESOURCE_ID.
  • logName: Log tempat entri log berada:
    • Entri log pada waktu build memiliki ID log reasoning_engine_build.
    • Entri log untuk stdout dan stderr masing-masing memiliki ID log reasoning_engine_stdout dan reasoning_engine_stderr.
    • Entri log dari logging Python atau klien Cloud Logging akan memiliki ID log kustom berdasarkan kode Anda di Menulis log untuk agen.
  • trace dan span: untuk log saat melacak kueri.
  • severity: untuk tingkat keparahan entri log.
  • insertId: ID unik untuk entri log.
• labels: Peta pasangan kunci-nilai yang memberikan informasi tambahan tentang entri log. Label dapat ditentukan pengguna atau ditentukan sistem, dan berguna untuk mengategorikan log serta mempermudah penelusuran log di Logs Explorer.
• payload: konten entri log.

Berikut adalah contoh kueri untuk semua log INFO dari agen yang di-deploy dengan RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Anda dapat melihatnya di Logs Explorer di

https://https://console.cloud.google.com/logs/query;query=severity%3DINFO%0Aresource.labels.reasoning_engine_id%3D%22RESOURCE_ID%22;duration=DURATION?project=PROJECT_ID

dengan kueri yang telah dienkode URL dengan tepat dan parameter lainnya adalah sebagai berikut:

• DURATION: misalnya PT30M untuk 30 menit terakhir (atau PT10M untuk 10 menit terakhir), dan
• PROJECT_ID: Google Cloud project.

Untuk mengetahui detailnya, buka Membuat dan menyimpan kueri menggunakan bahasa kueri Logging.

Catatan: Logs Explorer tidak mendukung operasi gabungan, seperti menghitung jumlah entri log yang berisi pola tertentu. Untuk kueri yang lebih canggih yang mencakup operasi gabungan dan lainnya, buka Kueri log untuk agen.

Mengkueri log untuk agen

Untuk pendekatan terprogram dalam membuat kueri log, ada dua opsi umum:

• Structured Query Language (SQL). Log Analytics memungkinkan Anda membuat kueri tampilan log atau tampilan analisis.
  • Tampilan log memiliki skema tetap yang sesuai dengan entri log.
  • Tampilan Analytics memiliki skema yang didasarkan pada hasil kueri SQL.

• Python. Panggil Cloud Logging API melalui library klien untuk bahasa pemrograman Anda (Python dalam kasus ini).

Python

from google.cloud import logging

logging_client = logging.Client(project="PROJECT_ID")
logger = logging_client.logger("LOG_ID")  # E.g. "logging_client"
print("Listing entries for logger {}:".format(logger.name))
for entry in logger.list_entries(
    filter_="resource.labels.reasoning_engine_id=RESOURCE_ID"  # Optional
):
    timestamp = entry.timestamp.isoformat()
    print("* {}: {}".format(timestamp, entry.payload))

Setiap entry akan sesuai dengan LogEntry. Untuk mengetahui detail tentang argumen input ke logger.list_entries, buka referensi API.

SQL

Tampilan log:

SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

Tampilan Analytics:

SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`