Agent protokollieren

Wenn Sie Cloud Logging in bereitgestellten Agents verwenden möchten, haben Sie folgende Möglichkeiten:

• stdout / stderr: Standardmäßig (ohne zusätzliche Einrichtung) werden Logs, die in stdout und stderr geschrieben werden, an die Log-IDs reasoning_engine_stdout und reasoning_engine_stderr weitergeleitet. Sie müssen jedoch Text sein.
• Python-Logging: Der integrierte Python-Logger kann in Cloud Logging eingebunden werden. Im Vergleich zum Schreiben in stdout oder stderr werden hier strukturierte Protokolle unterstützt und die Einrichtung ist minimal.
• Cloud Logging-Client: Nutzer können strukturierte Protokolle schreiben und haben die vollständige Kontrolle über den Logging-Client (z.B. Festlegen des logName und des Ressourcentyps).

Logs für einen Kundenservicemitarbeiter schreiben

Wenn Sie Logs für einen Kundenservicemitarbeiter schreiben, sollten Sie Folgendes festlegen:

• severity: z.B. „info“, „warn“ oder „error“
• Nutzlast: der Inhalt des Logs (z.B. Text oder JSON)
• Zusätzliche Felder: zum Korrelieren von Logs (z.B. Trace/Span, Tags, Labels)

So protokollieren Sie beispielsweise die Eingabe jeder Suchanfrage beim Entwickeln eines Bots:

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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    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 Protokolleinträge generiert. Beispiel:

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

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

wird ein Logeintrag wie der folgende generiert:

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 Kundenservicemitarbeiter ansehen

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

1. Rufen Sie in der Google Cloud Console den Log-Explorer auf:

   Zum Log-Explorer

2. Wählen Sie oben auf der Seite Ihr Google Cloud -Projekt (entspricht PROJECT_ID) aus.

3. Wählen Sie unter Ressourcentyp die Option Vertex AI Reasoning Engine aus.

Abfragen erstellen

Mit dem Log-Explorer können Sie Abfragen nach und nach erstellen. Abfragen werden in der Regel anhand der folgenden Kriterien erstellt:

• Zeitachse: Sie können nach relevanten Logeinträgen nach Zeit suchen.
• scope: Suche nach relevanten Protokolleinträgen basierend auf kanonischen Attributen
  • resource: Sie wird von anderen Arten von Ressourcen in Ihrem Projekt getrennt.
    • type: Wird im Logs Explorer als „Vertex AI 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 Protokoll, zu dem der Logeintrag gehört:
    • Die Logeinträge zur Buildzeit haben die Log-ID reasoning_engine_build.
    • Die Logeinträge für stdout und stderr haben die Log-IDs reasoning_engine_stdout und reasoning_engine_stderr.
    • Die Logeinträge aus dem Python-Logging oder dem Cloud Logging-Client haben benutzerdefinierte Log-IDs, die auf Ihrem Code in Logs für einen Kundenservicemitarbeiter schreiben basieren.
  • trace und span: für Logs beim Abfragen von Traces
  • severity: für den Schweregrad des Logeintrags.
  • insertId: Die eindeutige Kennung für einen Logeintrag.
• labels: Eine Zuordnung von Schlüssel/Wert-Paaren, die zusätzliche Informationen zum Logeintrag enthält. Die Labels können benutzerdefiniert oder systemdefiniert sein. Sie sind nützlich, um Protokolle 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 von einem bereitgestellten Agenten mit RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Sie können sie im Log-Explorer unter

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

wobei die Abfrage korrekt URL-codiert ist und die anderen Parameter folgendermaßen lauten:

• 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.

Hinweis :Der Log Explorer unterstützt keine Aggregationsvorgänge wie das Zählen der Anzahl der Logeinträge, die ein bestimmtes Muster enthalten. Weitere Informationen zu erweiterten Abfragen, die unter anderem Aggregationsvorgänge umfassen, finden Sie unter Logs für einen Kundenservicemitarbeiter abfragen.

Logs für einen Kundenservicemitarbeiter abfragen

Für einen programmatischen Ansatz zur Abfrage von Protokollen gibt es zwei gängige Optionen:

• Structured Query Language (SQL). Mit Log Analytics können Sie Logansichten oder Analyseansichten abfragen.
  • Protokollansichten haben ein festes Schema, das den Logeinträgen entspricht.
  • Analytics-Ansichten 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 (in diesem Fall Python) auf.

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

Jedem entry entspricht ein LogEntry. Weitere Informationen 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`

Analytics-Datenanzeige:

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