Logging einrichten

Logging ist unerlässlich, um das Verhalten Ihrer Agenten zu verstehen und Fehler zu beheben. Wenn Sie einen Agenten in der Agent Runtime bereitstellen, können Sie mit Cloud Logging Aktivitäten verfolgen, die Ausführung überwachen und die Leistung optimieren. In diesem Dokument werden die Methoden zum Schreiben und Aufrufen von Logs für Ihre Agenten beschrieben.

Wenn Sie mit Cloud Logging in Agenten arbeiten möchten, die in der Agent Runtime bereitgestellt werden, verwenden Sie eine der folgenden Methoden:

stdout oder stderr: Standardmäßig (ohne zusätzliche Einrichtung) werden Logs, die in stdout und stderr geschrieben werden, an die Log-IDs reasoning_engine_stdout bzw. reasoning_engine_stderr weitergeleitet. Die Einschränkung besteht darin, dass sie Text sein müssen.
Python-Logging: Der integrierte Python-Logger kann in Cloud Logging eingebunden werden. Im Vergleich zum Schreiben in `stdout` oder `stderr` werden strukturierte Logs unterstützt und die Einrichtung ist minimal.
Cloud Logging-Client: Nutzer können strukturierte Logs schreiben und haben die vollständige Kontrolle über den Logger (z. B. Festlegen von logName und Ressourcentyp).

Logs für einen Agenten schreiben

Wenn Sie Logs für einen Agenten schreiben, legen Sie Folgendes fest:

severity: z. B. „info“, „warn“, „error“
payload: Der Inhalt des Logs (z. B. Text oder JSON)
additional fields: Zur Korrelation von Logs (z. B. Trace/Span, Tags, Labels)

Beispiel: So protokollieren Sie die Eingabe jeder Abfrage beim Entwickeln eines Agenten:

stdout oder 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
        )

Python-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.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,
        )

Cloud Logging-Client

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,
        )

Wenn der Agent bereitgestellt und abgefragt wird, werden Log einträge generiert. Beispiel: Der folgende Code:

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

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

generiert einen Logeintrag ähnlich dem folgenden:

stdout oder 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"
}

Python-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-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"
}

Cloud Logging-Client

{
  "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"
}

Logs für einen Agenten aufrufen

Sie können Ihre Logeinträge mit dem Log-Explorer aufrufen:

Bitten Sie Ihren Administrator, Ihnen die Rolle Logs Viewer (roles/logging.viewer) für Ihr Projekt zuzuweisen, um die Berechtigung zum Aufrufen von Logs im Log-Explorer zu erhalten.
Rufen Sie in der Google Cloud Console den Log-Explorer auf:

Zum Log-Explorer
Wählen Sie oben auf der Seite Ihr Google Cloud Projekt aus (entsprechend PROJECT_ID).
Wählen Sie unter Ressourcentyp die Option Gemini Enterprise Agent Platform Reasoning Engine aus.

Bei Agenten, die auf dem Agent Development Kit basieren, können Sie Logs für Ihren Agenten auch in der Google Cloud Console über das Agent Runtime Dashboard aufrufen.

Laufzeitabfragen

Sie können Logs in Cloud Logging nach jedem unterstützten Vorgang eines bereitgestellten Agenten filtern. Filtern Sie dazu die Logs anhand des zugrunde liegenden REST-Endpunkts für jede Vorgangsabfrage:

POST /api/reasoning_engine: Für Abfragen an synchrone und asynchrone Methoden.
POST /api/stream_reasoning_engine: Für Abfragen an Streaming- und asynchrone Streaming-Methoden.
POST /api/bidi_reasoning_engine: Für Abfragen an bidirektionale Streaming Methoden.

Laufzeitabfragen werden je nach Feld api_mode in der Liste der unterstützten Vorgänge eines bereitgestellten Agenten an die REST-Endpunkte weitergeleitet.

Abfragen erstellen

Sie können den Log-Explorer verwenden, um Abfragen zu erstellen inkrementell. Abfragen werden in der Regel auf der Grundlage der folgenden Überlegungen erstellt:

timeline: Nach relevanten Logeinträgen anhand der Zeit suchen
scope: Nach relevanten Logeinträgen anhand kanonischer Attribute suchen
- resource: Von anderen Ressourcentypen in Ihrem Projekt trennen.
  - type: Wird im Log-Explorer als "Gemini Enterprise Agent Platform Reasoning Engine" und im Logeintrag als "aiplatform.googleapis.com/ReasoningEngine" angezeigt.
  - labels: Für den Standort (LOCATION), das Projekt PROJECT_ID und die Ressource RESOURCE_ID.
- logName: Das Log, zu dem der Logeintrag gehört:
  - Die Logeinträge zur Build-Zeit haben die Log-ID reasoning_engine_build.
  - Die Logeinträge für stdout und stderr haben die Log-ID reasoning_engine_stdout bzw. reasoning_engine_stderr.
  - Die Logeinträge aus dem Python-Logging oder dem Cloud Logging-Client haben benutzerdefinierte Log-IDs, die auf Ihrem Code unter Logs für einen Agenten schreiben basieren.
- trace und span: Für die Logs beim Tracing von Abfragen.
- severity: Für den Schweregrad des Logeintrags.
- insertId: Die eindeutige ID für einen Logeintrag.
labels: Eine Map mit Schlüssel/Wert-Paaren, die zusätzliche Informationen zum Logeintrag enthält. Die Labels können benutzerdefiniert oder vom System definiert sein und sind nützlich, um Logs zu kategorisieren und die Suche im Log-Explorer zu erleichtern.
payload: Der Inhalt des Logeintrags.

Das folgende Beispiel zeigt eine Abfrage für alle INFO Logs eines bereitgestellten Agenten mit RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Sie können sie im Log-Explorer unter

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

aufrufen. Die Abfrage wurde entsprechend URL-codiert und die anderen Parameter sind:

DURATION: z. B. PT30M für die letzten 30 Minuten oder PT10M für die letzten 10 Minuten und
PROJECT_ID: das Google Cloud Projekt.

Weitere Informationen finden Sie unter Abfragen mit der Logging-Abfragesprache erstellen und speichern.

Logs für einen Agenten abfragen

Für einen programmatischen Ansatz zum Abfragen von Logs gibt es zwei gängige Optionen:

Structured Query Language (SQL). Log Analytics ermöglicht das Abfragen von Logansichten oder Analyseansichten.
- Logansichten haben ein festes Schema, das Logeinträgen entspricht.
- Analyseansichten haben ein Schema, das auf den Ergebnissen einer SQL-Abfrage basiert.
Python. Rufen Sie die Cloud Logging API über die Clientbibliothek für Ihre Programmiersprache auf (in diesem Fall Python).

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))

Jeder entry entspricht einem LogEntry. Details zu den Eingabeargumenten für logger.list_entries finden Sie in der API-Referenz.

SQL

Logansicht:

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

Analyseansicht:

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

Logging einrichten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Logs für einen Agenten schreiben

stdout oder stderr

Python-Logging

Cloud Logging-Client

stdout oder stderr

Python-Logging

Cloud Logging-Client

Logs für einen Agenten aufrufen

Laufzeitabfragen

Abfragen erstellen

Logs für einen Agenten abfragen

Python

SQL

Logging einrichten