Auf Traces und Spans zugreifen

In diesem Dokument wird beschrieben, wie Sie auf Traces und Spans zugreifen und diese ansehen, die von Ihrer Gemini Enterprise App generiert wurden. Traces und Spans bieten detaillierte Einblicke in die Leistung und den Ausführungsablauf von Anfragen in Ihrer Anwendung, z. B. bei der Verwendung des Assistenten oder von Agenten.

Sie können Trace-Daten entweder im Trace-Explorer oder direkt in einzelnen Agenten auf dem Tab Traces des Agenten aufrufen.

Wichtige Konzepte

In diesem Abschnitt werden wichtige Konzepte im Zusammenhang mit der Beobachtbarkeit in Gemini Enterprise vorgestellt.

Konzept Beschreibung
Trace Ein Trace ist eine Sammlung von Spans, die eine einzelne Anfrage oder Transaktion darstellen, während sie durch verschiedene Dienste und Komponenten fließt.

Ein Trace stellt beispielsweise den gesamten Lebenszyklus einer Anfrage dar. Dazu gehören das Stellen einer Frage an den Gemini Enterprise-Assistenten, die Antwort des Gemini Enterprise-Assistenten und alle nachfolgenden Aktionen, die durch die Antwort ausgelöst werden, z. B. das Senden einer E‑Mail.
Span Ein Span ist eine einzelne, zeitlich begrenzte Arbeitseinheit innerhalb eines Trace. Er stellt einen bestimmten Vorgang dar, z. B. einen Funktionsaufruf, eine API-Anfrage oder eine Datenbankabfrage. Jeder Span enthält Details wie Start- und Endzeit, eine eindeutige ID und die Beziehung zu anderen Spans. Diese Beziehungen bilden zusammen einen Trace.
Span-Logs Span-Logs sind mit Zeitstempeln versehene, freiformatige Nachrichten oder Ereignisse, die einem bestimmten Span zugeordnet sind. Sie liefern detaillierte, kontextbezogene Informationen zur Ausführung eines Spans, die Nutzern helfen, Probleme zu beheben und den Ablauf einer Anfrage zu verstehen.

Hinweis

Sie benötigen Folgendes:

  • Die Rolle Gemini Enterprise Admin oder die Google Cloud Console-Rolle „Gemini Enterprise User“.

  • Eine vorhandene Gemini Enterprise-Webanwendung. Informationen zum Erstellen einer neuen Anwendung finden Sie unter Anwendung erstellen.

  • Für den Zugriff auf Traces benötigen Sie die Rolle Cloud Trace-Nutzer (roles/cloudtrace.user).

  • Aktivieren Sie die Beobachtbarkeitseinstellung Instrumentierung von OpenTelemetry-Traces und ‑Logs aktivieren. Je nach Agententyp aktivieren Sie diese Funktion in den Konfigurationen auf Anwendungsebene (für den Core Assistant-Agenten) oder auf dem Tab Konfiguration des Agenten (für von Mitarbeitern erstellte Workflow Builder-Agenten und Deep Research-Agenten). Weitere Informationen finden Sie unter Einstellungen für die Beobachtbarkeit verwalten.

Datenaufbewahrung

Traces und Spans, die von Ihrer Gemini Enterprise App generiert werden, werden in Cloud Trace in Ihrem Google Cloud -Projekt gespeichert. Ihre Aufbewahrung unterliegt Cloud Trace. Standardmäßig werden Span-Daten in Cloud Trace 30 Tage lang aufbewahrt. Daten, die älter als die Aufbewahrungsdauer sind, werden automatisch gelöscht. Die verbindlichen und aktuellen Aufbewahrungswerte finden Sie in der Dokumentation zu Cloud Trace-Kontingenten und -Limits unter Cloud Trace-Aufbewahrungsdauer.

Auf Traces im Trace-Explorer zugreifen

So greifen Sie mit dem Trace Explorer auf Traces und Spans zu:

  1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf.

    Trace Explorer aufrufen

  2. Wählen Sie das Google Cloud -Projekt aus, in dem Ihre Gemini Enterprise-App erstellt wurde. Sie sehen alle Spans für Ihr Projekt.

  3. Klicken Sie in der Tabelle auf eine Span-ID, um die Trace-Details aufzurufen, einschließlich der Dauer des Spans und anderer Attribute.

    Screenshot des Trace-Explorers in der Google Cloud -Console mit einer Liste von Spans mit Spalten für Span-ID, Trace-ID, Startzeit, Dauer und Dienst.

Traces filtern und suchen

Im Trace-Explorer für Ihr Projekt können Sie Ausführungen von Gemini Enterprise-Agenten und Daten-Connectors mithilfe dieser Filter, Abfrageparameter und Attribute isolieren und analysieren:

  • Facettenfilter:
    • Dienst: Filtern Sie nach AssistantService oder connectorsexecution, um die Anfragepfade für den Plattform-Agenten und den Daten-Connector zu isolieren.
    • Span: Filtern Sie nach /AssistantService.StreamAssist, um die Root-Nutzer-Turn-Spans zu finden, oder suchen Sie nach untergeordneten Spans wie execute_tool <tool_name> und invoke_connector <connector>.
  • Direkte Trace-ID-Suche: Traces können direkt über die standardmäßige 32-stellige W3C-Trace-ID gefunden werden, die aus den x-cloud-trace-context-Antwortheadern von StreamAssist extrahiert werden kann.
  • Benutzerdefinierte Attribute: Fragen Sie das Attribut gemini_enterprise.assist_token für execute_tool- oder invoke_connector-Spans ab, um Legacy-Assist-Tokens auf Turn-Ebene dem W3C-Trace-Wasserfalldiagramm zuzuordnen.
  • Ressourcenattribute: Jeder exportierte Span enthält cloud.region, den
  • Ressourcenattribute: Jeder exportierte Span enthält das Attribut cloud.region. Dieses Attribut stellt den Gemini Enterprise-Bereitstellungsstandort dar, der die Anfrage verarbeitet hat, z. B. global, us oder eu. Sie können nach diesem Attribut filtern, um die Leistung in verschiedenen Regionen zu vergleichen. Dieser Vergleich ist nützlich, wenn ein Daten-Connector an einem Standort erfolgreich ist, an einem anderen jedoch fehlschlägt. Dieser Wert stellt den Standort dar, an dem Ihre Anwendung bereitgestellt wird, nicht die Region, in der die Drittanbieter-Datenquelle gehostet wird. Informationen zum Anwenden dieses Filters finden Sie unter Span-Filter anwenden.

Auf Traces für KI-Agenten zugreifen

Sie können Trace-Spans auch direkt für einzelne Agenten auf dem Tab Traces des Agenten aufrufen. Dort finden Sie eine detaillierte chronologische Zusammenfassung der Span-Trace-Einträge und der übergeordneten und untergeordneten Ausführungsstrukturen.

So greifen Sie auf Traces für einen Agenten zu:

  1. Rufen Sie in der Google Cloud Console Ihre Anwendung auf und klicken Sie dann auf Agenten.
  2. Wählen Sie den Agenten aus, den Sie prüfen möchten, und klicken Sie dann auf den Tab Traces.

Trace-Zusammenfassungstabelle

In der Haupttabelle auf dem Tab Traces werden die folgenden Informationen für jeden Trace-Span angezeigt:

  • Status: Der aktuelle Status des Traces (derzeit wird Nicht festgelegt angezeigt).
  • Trace-Span-ID: Die eindeutige Kennung für den Trace-Span. Klicken Sie auf den Link mit der Span-ID, um die Details aufzurufen.
  • Span-Name: Eine kurze Beschreibung der Arbeit, die der Span ausführt. Beispiele für Spans für Gemini Enterprise-Daten-Connectors:
    • execute_tool <tool_name>: Wird während der Tool-Dispatch-Ebene in der Agent Runtime ausgegeben (z. B. execute_tool federated_search).
    • invoke_connector <connector>: Wird von der Connector-Ausführungsebene generiert, um die Anfragelogik für den spezifischen Connector (z. B. invoke_connector jira oder invoke_connector servicenow) darzustellen, die die standardmäßigen dienstseitigen RPC-Spans ersetzt.
  • Span-Typ: Der Typ des Spans. Folgende Optionen sind verfügbar:
    • Agent to Tool: Ein Aufruf eines externen Tools durch den Agenten (wird für execute_tool- und invoke_connector-Vorgänge wiederverwendet).
    • Invoke Agent: Ein Aufruf eines KI-Agenten.
    • Agent to Model: Eine Anfrage des KI-Agenten an ein Large Language Model.
  • Dauer: Die Zeit, die für den Abschluss des Trace-Spans benötigt wurde (in Minuten).
  • Eingabe: Die Eingabedaten oder die Nachricht, die an den Span gesendet wurde, falls vorhanden.
  • Ausgabe: Das vom Span zurückgegebene Ausgabeergebnis, falls vorhanden.
  • Startzeit: Der genaue Zeitstempel, zu dem die Ausführung des Span begonnen hat.

Detaillierte Trace-Ansicht

Wenn Sie auf eine Trace-Span-ID klicken, wird eine Detailseite mit folgenden Informationen geöffnet:

  1. Zusammenfassung: Hier sehen Sie die Metadaten der Referenz, einschließlich Beginn, Dauer und Gesamtzahl der Spans. Sie können auf In Cloud Trace ansehen klicken oder zwischen den Ansichten Diagramm und Zeitachse wechseln.
  2. Visualisierungen: Wechseln Sie zwischen einer grafischen Hierarchie oder einer Zeitachsenansicht, in der die über- und untergeordneten Beziehungen aller Trace-Spans angezeigt werden.
  3. Details zum ausgewählten Span: Wählen Sie einen einzelnen Span aus, um detaillierte Abschnitte anzuzeigen, die Folgendes enthalten können:
    • Zusammenfassung: Zeigt den Namen des Span, den Zieldienst, die Gesamtzahl der Spans mit dieser Aktion und die Gesamtdauer (in Sekunden) an.
    • Protokolle: Sehen Sie sich relevante Ereignisdetails an, falls konfiguriert. Klicken Sie auf Logs ansehen, um direkt zu den Standardlogs zu gelangen.
    • Bewertung: Zeigt alle Bewertungsergebnisse an, sofern konfiguriert.
    • Eingabe und Ausgabe: Vollständige Anfrage- und Antwortnutzlasten.
    • Logs und Ereignisse: Liste der Ereignisse, die während der Ausführung dieses Spans aufgetreten sind.
    • Stacktraces: Fehlerdetails, wenn die Ausführung eines Spans fehlschlägt.
    • Metadaten und Links: Links, die auf zugehörige Cloud Explorer-Entitäten verweisen.
    • Attribute: Ressourcen-Tags und zusätzliche Schlüssel/Wert-Paare für die Beobachtbarkeit.

Screenshot des Tabs „Traces“ in der Google Cloud -Konsole mit einer Zeitachse der Spans und der Span-Zusammenfassung

Übergeordnete/untergeordnete Span-Hierarchie

Bei der Ausführung von Daten-Connectors hilft die Verschachtelung von übergeordneten und untergeordneten Spans innerhalb eines einzelnen W3C-Traces, genau zu bestimmen, wo Latenz oder Fehler auftreten:

  1. /AssistantService.StreamAssist: Root-C++-Plattform-Span, der die Anfrage initiiert.
  2. invoke_agent core_assistant: Der Ausführungszeitraum des KI-Agenten.
  3. execute_tool <tool_name>: Der aktive Toolausführungsbereich (z. B. execute_tool federated_search).
  4. invoke_connector <connector_name> (z. B. invoke_connector jira oder invoke_connector servicenow): Der Ausführungsbereich des Connectors, der den Anfragelebenszyklus zum Drittanbieter-Endpunkt darstellt.

Experimentelle Telemetrie für semantische Konventionen der generativen KI

Zusätzlich zur stabilen Telemetrie enthalten Gemini Enterprise-Trace-Spans umfangreichere Metadaten, die auf den semantischen Konventionen für generative KI von OpenTelemetry basieren. OpenTelemetry klassifiziert diese Konventionen als Entwicklungsstatus. Dieser Status gilt für Spezifikationen in der Anfangsphase, die sich ändern oder entfernt werden können und auf die man sich in der Produktion nicht verlassen sollte. Da diese Konventionen noch nicht stabil sind, ist diese Gemini Enterprise-Telemetrie experimentell. Diese Spans enthalten gen_ai.*-Attribute, die die Aktivitäten von Agenten, Modellen und Tools beschreiben, z. B. die Ausführung von Agenten und Tools sowie die Schritte für Prompts und Antworten.

Prompt- und Antwortinhalte in Trace-Spans (z. B. Prompt-Text und generierte Antworten) werden nur angezeigt, wenn Ihre Beobachtbarkeitseinstellungen das Logging von Prompt-Eingaben und Antwortausgaben zulassen. Andernfalls wird der Inhalt unkenntlich gemacht oder weggelassen. Informationen zum Ändern dieser Einstellungen finden Sie unter Beobachtbarkeitseinstellungen verwalten.