Traces suchen und analysieren

Auf der Seite Trace Explorer können Sie eine zusammengefasste Darstellung Ihrer Trace-Daten aufrufen oder einzelne Traces oder Traces mit bestimmten Labels suchen und analysieren.

Diese Funktion wird nur für Google Cloud-Projekte unterstützt.

Die Seite Trace Explorer

Damit Sie Trends und Muster in Ihren Trace-Daten leichter erkennen können, werden die Latenzdaten zusammengefasst und in Diagrammen dargestellt. In der Heatmap, der Standardvisualisierung, wird die Anzahl der Spannweiten in einer Zelle durch Farbe dargestellt. Zellen mit vielen Spannweiten werden dunkler dargestellt als Zellen mit wenigen Spannweiten. Sie können eine Zelle auswählen oder die Kurzinfo einer Zelle aktivieren, um weitere Informationen zu erhalten. In den anderen Visualisierungen können Sie die Latenz als Prozentil und Informationen zur Rate sehen. Bei allen Visualisierungen können Sie die X-Achse mit dem Mauszeiger maximieren. Bei Liniendiagrammen können Sie die X- und Y-Achsen maximieren.

Wenn Sie ein Problem untersuchen, können Sie sich einen bestimmten Trace oder nur Spannen mit bestimmten Eigenschaften ansehen:

  • Wenn Sie die ID eines Traces kennen, klicken Sie in der Symbolleiste auf Trace suchen und geben Sie die Trace-ID in das Dialogfeld ein. Als Nächstes können Sie in den Spannen und Attributen im Trace nach Keywords suchen .

  • Wenn Sie sich die zusammengefassten Daten ansehen, können Sie mithilfe von Filtern nach bestimmten Zeiträumen suchen. Sie können die Daten beispielsweise so filtern, dass nur die Spannen für einen bestimmten Dienst angezeigt werden. Als Nächstes können Sie einen zweiten Filter hinzufügen, der die Anzeige auf Bereiche für einen bestimmten Dienst beschränkt, für den ein Fehler gemeldet wird.

In den tabellarischen Daten können Sie Details zu einzelnen Spannen sehen und Ausreißer erkennen. Wenn Sie beispielsweise die Spanne mit dem höchsten Latenzwert ermitteln möchten, wählen Sie den Tab Spannen aus und sortieren Sie die Daten dann nach Latenz. Wenn Sie die Dienste finden möchten, die Fehler verursachen, filtern Sie die Daten nach Span-Status und wählen Sie dann den Tab Gruppiert aus. Dort werden Daten nach Span und Dienstname zusammengefasst. Jede Zeile in der Tabelle enthält einen Link zu detaillierten Informationen.

Welche Trace-Daten auf der Seite Trace-Explorer angezeigt werden, hängt von folgenden Faktoren ab:

  • Die Projekte, in denen nach Trace-Daten gesucht wird. Standardmäßig wird nur in dem Projekt nach Trace-Daten gesucht, das in der Projektauswahl ausgewählt wurde. Sie können die Seite jedoch so konfigurieren, dass die Liste der Projekte in einem Trace-Bereich durchsucht wird.
  • Ihre IAM-Berechtigungen (Identity and Access Management) für die gesuchten Projekte. Wenn Sie nicht berechtigt sind, Trace-Daten für ein Projekt aufzurufen, wird in der Google Cloud Console eine Warnmeldung angezeigt und die Daten aus diesem Projekt werden nicht angezeigt.
  • Die Einstellung für den Zeitraum.
  • Die von Ihnen angewendeten Filter.

Im Folgenden finden Sie weitere Informationen dazu, wie Sie Ihre Trace-Daten finden und analysieren.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace-Nutzer (roles/cloudtrace.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, um Trace-Daten in der Google Cloud Console aufzurufen und einen Trace-Bereich auszuwählen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Aufrufen von Trace-Daten über die Google Cloud Console und zum Auswählen eines Trace-Bereichs erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Trace-Daten in der Google Cloud Console aufzurufen und einen Trace-Umfang auszuwählen:

  • So wählen Sie den Umfang eines Traces aus: cloudtrace.traceScopes.[get, list]
  • So rufen Sie den Standard-Eintragsumfang ab: observability.scopes.get

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu Rollen finden Sie unter Zugriff mit Identity and Access Management steuern.

Aggregierte Trace-Daten ansehen

So rufen Sie die zusammengefassten Informationen zu Ihren Trace-Daten auf:

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

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

    Nach dem Schreiben der ersten Trace-Daten in ein Google Cloud-Projekt kann es einige Minuten dauern, bis diese Daten angezeigt werden. Wenn nach einigen Minuten keine Trace-Daten angezeigt werden, gibt es möglicherweise keine Daten für Ihr Projekt oder es liegt ein Konfigurationsproblem vor. Informationen zur Behebung dieser Probleme finden Sie unter Fehlerbehebung: Keine Daten in der Trace-Oberfläche.

  2. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud-Projekt aus.

  3. Optional: Mit dem Element Scope können Sie konfigurieren, in welchen Projekten nach Trace-Daten gesucht werden soll:

    • Wenn Sie die in Ihrem Projekt gespeicherten Trace-Daten sehen möchten, legen Sie im ersten Menü des Elements Scope (Umfang) die Option Project (Projekt) oder _Default (Standard) fest. Diese beiden Einstellungen sind gleichwertig.

    • Wenn Sie die in mehreren Projekten gespeicherten Trace-Daten sehen möchten, maximieren Sie das erste Menü des Elements Scope (Umfang), wählen Sie Trace scope (Trace-Umfang) und dann den Trace-Umfang aus, in dem diese Projekte aufgeführt sind. Nachdem Sie eine Auswahl getroffen haben, wird im Menü Scope (Umfang) das Symbol für den Tracebereich  und der Name des ausgewählten Tracebereichs angezeigt.

    Welche Daten zurückgegeben werden, hängt von Ihren IAM-Rollen in den Projekten ab, in denen Sie suchen. Wenn die gesuchten Projekte beispielsweise ein Google Cloud-Projekt enthalten, auf das Sie keinen Zugriff haben, werden keine Trace-Daten für dieses Projekt zurückgegeben.

    Weitere Informationen finden Sie unter Trace-Bereiche erstellen und verwalten.

  4. Optional: Aktualisieren Sie den Zeitraum mit der Auswahl für den Zeitraum oder indem Sie mit dem Mauszeiger einen Bereich auf der X-Achse markieren.

  5. Sehen Sie sich die Diagramme an, in denen Muster und Trends in Ihren Messdaten dargestellt sind:

    • Wenn Sie Informationen zu Daten zur Spannlatenz abrufen möchten, wählen Sie im Menü Diagrammansicht die Option Spannungsdauer (Heatmap) aus. Die Farbintensität ist proportional zur Anzahl der Übergänge. Bewegen Sie den Mauszeiger auf eine Zelle, um Informationen zu erhalten. Die Kurzinfo enthält die Anzahl der Zeiträume, Datum und Uhrzeit sowie das Zeitintervall der Zelle.

    • Wenn Sie Latenztrends sehen möchten, wählen Sie im Menü Diagrammansicht die Option Spannungsdauer (Perzentil) aus. Im Diagramm für die Dauer werden das 50., 90., 95. und 99. Perzentil angezeigt.

    • Wenn Sie den Antwortstatus in Abhängigkeit von der Zeit sehen möchten, wählen Sie im Menü Diagrammansicht die Option Zeitspanne aus. Im Diagramm sehen Sie die Häufigkeit, mit der Spannen an Ihr Projekt gesendet werden.

  6. Auf dem Tab Spans finden Sie tabellarische Daten mit einzelnen Spans. Auf dem Tab Gruppiert sind Spans nach Dienst und Name gruppiert.

    Jede Zeile in den Tabellen enthält einen Span oder eine Gruppe sowie einen Link zu detaillierten Informationen und einigen Messwerten. Auf dem Tab Gruppiert sind beispielsweise die Fehlerrate und die Anzahl der Spannen in der Gruppe zu sehen.

    Wenn Sie Ausreißer finden möchten, wählen Sie eine Spaltenüberschrift aus, um die Tabelle zu sortieren.

  7. Fügen Sie Filter hinzu, um die angezeigten Spans einzuschränken. Sie können beispielsweise nach Dienstname und Status filtern. Wenn Sie einen Filter hinzufügen oder entfernen, werden die Daten auf der Seite Trace-Explorer aktualisiert und es werden nur die Bereiche angezeigt, die allen angewendeten Filtern entsprechen.

    So ändern Sie die Filtereinstellungen:

    • Wählen Sie im Bereich Bereichsfilter die gewünschten Filter aus.

      Im Bereich Bereichsfilter sind nur die gängigsten Filter aufgeführt. Wenn Sie nach einem Attribut filtern möchten, das nicht aufgeführt ist, verwenden Sie die Filterleiste.

    • Wenn Sie einen Filter über die Leiste Filter hinzufügen möchten, wählen Sie Filter hinzufügen aus und nehmen Sie die erforderlichen Einstellungen vor.

      Wenn Sie nach einem Attribut filtern möchten, das nicht im Optionsmenü aufgeführt ist, wählen Sie Attributfilter hinzufügen aus und fügen Sie dann den benutzerdefinierten Schlüssel und Wert hinzu. Wenn Sie beispielsweise den Schlüssel auf /http/status_code und den Wert auf 200 festlegen, lautet der Filter /http/status_code: 200. Wenn der Filter mit beliebigen Werten übereinstimmen soll, wählen Sie Beliebiger Wert aus.

Traces nach ID suchen

Wenn Sie einen Vorfall oder Fehler beheben, kennen Sie möglicherweise die Trace-ID. So können Sie diesen Trace untersuchen:

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

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

  2. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud-Projekt aus.

  3. Klicken Sie in der Symbolleiste auf Nach Trace suchen und geben Sie die Trace-ID ein.

    Wenn Sie eine gültige ID eingeben, wird das Flyout Details geöffnet. Dort finden Sie Informationen zum Trace und seinen Spans. Mit den Optionen in diesem Bereich können Sie den Trace untersuchen. Sie können beispielsweise in den Bereichen nach Keywords suchen.

Trace analysieren

So rufen Sie einen Trace oder eine Spanne auf:

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

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

    Nach dem Schreiben der ersten Trace-Daten in ein Google Cloud-Projekt kann es einige Minuten dauern, bis diese Daten angezeigt werden. Wenn nach einigen Minuten keine Trace-Daten angezeigt werden, gibt es möglicherweise keine Daten für Ihr Projekt oder es liegt ein Konfigurationsproblem vor. Informationen zur Behebung dieser Probleme finden Sie unter Fehlerbehebung: Keine Daten in der Trace-Oberfläche.

  2. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud-Projekt aus.

  3. Führen Sie einen der folgenden Schritte aus:

    • Rufen Sie den Tabellenbereich der Seite Trace Explorer auf und wählen Sie einen Eintrag aus der Tabelle aus, der Spannen oder Zusammenfassungsinformationen enthält, nachdem Sie die Daten nach Dienst und Spannenname gruppiert haben.

    • Klicken Sie auf der Seite Trace Explorer in der Symbolleiste auf Nach Trace suchen und geben Sie die Trace-ID ein.

    Das Flyout Details wird geöffnet und zeigt einen Trace und seine Spannweiten an:

    • In der Spalte Name wird die Aufrufhierarchie angezeigt. Der erste Eintrag enthält die Trace-ID.
    • Die Spalte Dienst wird aus dem OpenTelemetry-Attribut service.name extrahiert, wenn dieses Attribut festgelegt ist. Wenn dieses Attribut nicht festgelegt ist und der Dienst in der App Engine ausgeführt wird, wird der App Engine-Dienstname angezeigt. Andernfalls wird kein Dienst angegeben.
    • Die Länge des Latenzbalkens entspricht dem Latenzwert.
    • Die Farbe der Latenzleiste gibt den Status an. Ein blauer Latenzbalken gibt an, dass der Vorgang erfolgreich abgeschlossen wurde, während ein roter Latenzbalken auf einen Fehler hinweist.
    • Ein Kreis auf einer Latenzbalken gibt an, dass der Zeitspanne ein Logeintrag oder Ereignis zugeordnet ist. Wenn Sie dieses Verhalten ändern möchten, verwenden Sie das Menü Protokolle und Ereignisse.

  4. Optional: Im Feld Im Trace suchen können Sie nach dem Namen der Spanne, dem Dienstnamen und den Attributen in einem Trace suchen.

    Wenn Sie beispielsweise GET eingeben, wird der Text im Span-Namen, Dienstnamen oder im Bereich Attribute, in dem GET angezeigt wird, ohne Berücksichtigung der Groß- und Kleinschreibung hervorgehoben.

    Sie können nicht mit einem regulären Ausdruck suchen und auch keine Protokolle, Ereignisse oder Metadaten durchsuchen.

  5. Wenn Sie die Details einer bestimmten Spanne aufrufen möchten, wählen Sie sie aus und rufen Sie die zugehörigen Attribute und Ereignisse auf. Weitere Informationen finden Sie im nächsten Abschnitt.

Attribute und Ereignisse ansehen

In diesem Abschnitt wird beschrieben, wie Sie Labels, Protokolle und Ereignisse aufrufen.

Labels anzeigen

Die Labels, die mit dem Span verknüpft sind, finden Sie auf dem Tab Attribute. Informationen zu Labels finden Sie unter Trace-Labels.

Logs und Ereignisse ansehen

Die zugehörigen Logs und Ereignisse finden Sie auf dem Tab Protokolle und Ereignisse. Weitere Informationen zu Ereignisanmerkungen finden Sie unter Ereignis-Spans mit Anmerkungen versehen.

Wenn Sie einen Logeintrag aufrufen möchten, klicken Sie auf  Mehr anzeigen.

Sie können auch die Schaltfläche Protokolle ansehen auswählen. Daraufhin wird die Seite „Log-Explorer“ mit der Abfrage geöffnet, die so festgelegt ist, dass nach einer bestimmten Spur, einem bestimmten Zeitraum und einem bestimmten Zeitraum gefiltert wird. Diese Abfrage gibt möglicherweise keine Logeinträge zurück.

Generative AI-Ereignisse ansehen

Auf dem Tab GenAI finden Sie Ereignisse im Zusammenhang mit generativen KI-Agenten. Dieser Tab ist verfügbar, wenn die an Trace gesendeten Spans den OpenTelemetry-Semantikkonventionen für generative KI-Systeme entsprechen. Dies führt zu Nachrichten, deren Namen mit gen_ai beginnen.

Attribute sind Schlüssel/Wert-Paare, die eine bestimmte Eigenschaft beschreiben. Im Folgenden finden Sie Beispiele für Attribute eines generativen KI-Systems:

  • gen_ai.system: Gibt das System an, das die Funktionen für die generative KI bereitstellt.
  • gen_ai.request.model: Gibt das Modell an, an das die Anfrage gesendet wird.

Ereignisse, deren Name mit „gen_ai“ beginnt, beschreiben in der Regel einzelne Eingaben oder Ausgaben eines generativen KI-Systems. Dazu gehören System- und Nutzerprompts, Tooleingaben und -ausgaben sowie Modellantworten. Im Folgenden finden Sie Beispiele für Ereignisse aus einem generativen KI-System:

  • gen_ai.system.message: Ein Ereignis, das den Systemprompt aufzeichnet, der an ein generatives KI-Modell gesendet wurde. Der Systemvorschlag enthält Anweisungen für das Modell, die normalerweise nicht für den Endnutzer sichtbar sind und die die Interpretation des Vorschlags des Nutzers durch das Modell steuern.
  • gen_ai.user.message: Ein Ereignis, das den vom Nutzer bereitgestellten Prompt aufzeichnet, der an das Modell gesendet wurde.
  • gen_ai.assistant.message: Ein Ereignis, das die Ausgabe des Modells aufzeichnet. Es kann den Datensatz einer Toolausführung oder eine textbasierte Antwortausgabe enthalten. Eine Nachricht kann Antwortvorschläge enthalten, die von der Anwendung nicht verwendet werden.
  • gen_ai.choice: Mit diesem Ereignis wird erfasst, welche Kandidatenausgaben von der Anwendung verwendet werden.

Stacktraces ansehen

Auf dem Tab Stack-Traces können Sie Stack-Traces aufrufen.

Allgemeine Informationen und andere Metadaten aufrufen

Allgemeine Informationen zur Spanne und eine Tabelle mit Links zu anderen Spannen finden Sie auf dem Tab Metadaten und Links. Zu diesen Informationen gehören:

  • Span-ID: Die Span-ID ist eine 64-Bit-Ganzzahl, die nicht 0 ist. Weitere Informationen finden Sie unter TraceSpan.
  • Übergeordnete Span-ID
  • Projekt-ID
  • Start- und Endzeit
  • Tabelle mit Links zu anderen Bereichen

Jede Zeile in der Tabelle Glieder enthält einen Link zwischen dem aktuellen und einem anderen Span. Im Feld Attribute sind die Schlüssel/Wert-Paare für den verknüpften Bereich aufgeführt. Das Feld Trace verweist auf den Trace für den verknüpften Bereich. Wenn dieses Feld Aktuelle Trace enthält, befindet sich die verknüpfte Span in derselben Trace wie die aktuelle Span. Andernfalls enthält das Feld eine Trace-ID. Informationen zu Links findest du auf der API-Referenzseite für Links.

Nächste Schritte