Siapkan logging

Logging sangat penting untuk memahami dan men-debug perilaku agen Anda. Saat men-deploy agen ke Runtime Agen, Anda dapat menggunakan Cloud Logging untuk melacak aktivitas, memantau eksekusi, dan mengoptimalkan performa. Dokumen ini menjelaskan metode untuk menulis dan melihat log untuk agen Anda.

Untuk menggunakan Cloud Logging di agen saat di-deploy ke Runtime Agen, gunakan salah satu metode berikut:

stdout atau 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. Keterbatasannya adalah log harus berupa teks.
Logging Python: Logger Python bawaan dapat diintegrasikan dengan Cloud Logging. Dibandingkan dengan menulis ke stdout atau stderr, metode ini mendukung log terstruktur dan memerlukan penyiapan minimal.
Klien Cloud Logging: Pengguna dapat menulis log terstruktur, dan memiliki kontrol penuh atas logger (seperti, menetapkan logName dan jenis resource).

Menulis log untuk agen

Saat menulis log untuk agen, tentukan hal berikut:

tingkat keparahan: Seperti info, peringatan, error
payload: Konten log (seperti teks atau JSON)
kolom tambahan: Untuk mengorelasikan log (seperti pelacakan/rentang, 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 agen di-deploy dan dikueri, agen akan menghasilkan entri log. Misalnya, kode berikut:

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:

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:

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

Buka Logs Explorer
Pilihproject Anda (sesuai dengan PROJECT_ID) di bagian atas halaman. Google Cloud
Di Jenis Resource, pilih Gemini Enterprise Agent Platform Reasoning Engine.

Untuk agen berbasis Agent Development Kit, Anda juga dapat melihat log untuk agen Anda di konsol Google Cloud menggunakan dasbor Runtime Agen.

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 yang mendasarinya 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 streaming bidi metode.

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 bertahap. Kueri biasanya dibuat berdasarkan pertimbangan berikut:

linimasa: untuk menelusuri entri log yang relevan berdasarkan waktu
cakupan: untuk menelusuri entri log yang relevan berdasarkan atribut kanonis
- resource: pisahkan dari jenis resource lainnya di project Anda.
  - type: muncul sebagai "Gemini Enterprise Agent Platform Reasoning Engine" di Logs Explorer dan "aiplatform.googleapis.com/ReasoningEngine" di 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 memudahkan penelusuran 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.

Membuat kueri 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 analisis memiliki skema yang didasarkan pada hasil kueri SQL.
Python. Panggil Cloud Logging API melalui library klien untuk bahasa pemrograman Anda (Python dalam hal 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, lihat referensi API.

SQL

Tampilan log:

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

Tampilan analisis:

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

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

Menulis log untuk agen

stdout atau stderr

Logging Python

Klien Cloud Logging

stdout atau stderr

Logging Python

Klien Cloud Logging

Melihat log untuk agen

Kueri runtime

Membuat kueri

Membuat kueri log untuk agen

Python

SQL

Siapkan logging