Traces finden und ansehen

Wenn Sie eine aggregierte Darstellung Ihrer Trace-Daten aufrufen oder einzelne Traces oder Traces mit bestimmten Labels suchen und untersuchen möchten, verwenden Sie die Seite Trace Explorer.

Der folgende Screenshot zeigt, wie Trace-Daten dargestellt werden:

Diese Funktion wird nur für Google Cloud -Projekte unterstützt. Wählen Sie für App Hub-Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt aus.

Die Seite Trace Explorer

Damit Sie Trends und Muster in Ihren Trace-Daten leichter erkennen können, werden die Latenzdaten aggregiert und in Diagrammen dargestellt. In der Heatmap wird die Anzahl der Spannen in einer Zelle durch Farben dargestellt. Eine Zelle mit vielen Spannen hat eine dunklere Farbe als eine mit wenigen Spannen. In der Kurzinfo für jede Zelle werden Latenz und andere Informationen angezeigt. Außerdem können Sie sich Informationen zu Latenzperzentilen und zur Spannenrate ansehen.

Wenn Sie ein Problem untersuchen, möchten Sie möglicherweise einen bestimmten Trace oder nur Spans mit bestimmten Eigenschaften ansehen:

• Wenden Sie Filter an, um die angezeigten Spans einzuschränken. Sie können beispielsweise nach Dienst, Anwendung, Fehlerstatus und anderen Attributen filtern.

• Wenn Sie einen bestimmten Trace aufrufen möchten, verwenden Sie die Option Seitenaufruf Nach Trace suchen in der Symbolleiste.

Im Tabellenbereich können Sie Ausreißer identifizieren und Details zu einzelnen Zeiträumen aufrufen:

• Sie können die Zeilen der Tabs Spans (Spannen) und Grouped (Gruppiert) nach der Kopfzeile „Duration“ (Dauer) sortieren.

• Auf dem Tab Gruppiert sehen Sie, wie viele Spans von den verschiedenen Diensten generiert werden. Jede Zeile entspricht einem Dienst- und Spannen-Namen. Für jeden Eintrag werden Latenzstatistiken angezeigt.

Wenn Sie sich die Details eines Spans oder einer Gruppierung ansehen möchten, wählen Sie den entsprechenden Eintrag in einer Zeile im tabellarischen Bereich aus. Ein Flyout wird geöffnet, in dem der Bereich im Kontext des zugehörigen Traces angezeigt wird. In dieser Ansicht können Sie den Bereich und seine Attribute untersuchen sowie Ereignisse und Protokolldaten ansehen. Sie können auch in den Spans und Attributen des Traces nach Keywords suchen.

Die Tracedaten, die auf der Seite Trace Explorer verwendet werden, hängen von Folgendem ab:

• Die Projekte, in denen nach Tracedaten gesucht wird. Standardmäßig wird nur in dem Projekt, das in der Projektauswahl ausgewählt ist, nach Tracedaten gesucht. 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 durchsuchten Projekte. Wenn Sie nicht berechtigt sind, Trace-Daten für ein Projekt aufzurufen, wird in der Google Cloud Konsole eine Warnmeldung angezeigt und die Daten aus diesem Projekt werden nicht dargestellt.
• Die Einstellung für den Zeitraum.
• Die Filter, die Sie anwenden

Im Rest dieser Seite finden Sie weitere Informationen dazu, wie Sie Ihre Tracedaten finden und analysieren können.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace User (roles/cloudtrace.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen von Tracedaten über die Google Cloud Console und zum Auswählen eines Trace-Bereichs benötigen. 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 Tracedaten über die Google Cloud Konsole und zum Auswählen eines Tracebereichs erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Tracedaten in der Google Cloud -Konsole anzusehen und einen Trace-Bereich auszuwählen:

• So wählen Sie einen Trace-Bereich aus: cloudtrace.traceScopes.[get, list]
• So lesen Sie den Standardbereich für Traces: 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 IAM 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.

   Es kann einige Minuten dauern, nachdem die ersten Trace-Daten in ein Google Cloud Projekt geschrieben wurden, bis diese Daten angezeigt werden können. Wenn nach einigen Minuten keine Trace-Daten angezeigt werden, sind möglicherweise keine Daten für Ihr Projekt vorhanden oder es liegt ein Konfigurationsproblem vor. Informationen zur Behebung dieser Probleme finden Sie unter Fehlerbehebung: Keine Daten auf der Trace-Oberfläche.

2. Konfigurieren Sie die Seite Trace Explorer:

   1. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud -Projekt aus. Wählen Sie für App Hub-Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt aus.

   2. Optional: Konfigurieren Sie mit dem Element Scope, in welchen Projekten nach Tracedaten gesucht werden soll:

      • Wenn Sie die in Ihrem Projekt gespeicherten Tracedaten sehen möchten, legen Sie das erste Menü des Elements Scope auf Project oder _Default fest. Diese beiden Einstellungen sind gleichwertig.

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

      Die zurückgegebenen Daten hängen von Ihren IAM-Rollen für die durchsuchten Projekte ab. Wenn die durchsuchten 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.

   3. Optional: Aktualisieren Sie den Zeitraum mit der Zeitraumauswahl oder indem Sie mit dem Mauszeiger einen Bereich auf der x-Achse markieren.

      Sie können diesen Selektor beispielsweise auf Letzte 2 Wochen festlegen, wenn Sie sehen möchten, ob es Trends bei den Latenzdaten gibt. Die Daten für den Zeitraum werden 30 Tage lang gespeichert.

3. Heatmap ansehen:

   • Mit Farben lassen sich Trends und Ausreißer erkennen. Eine Zelle mit vielen Spannen hat eine dunklere Farbe als eine mit wenigen Spannen.

   • Rufen Sie die Details der Zelle mit der zugehörigen Kurzinfo auf. In der Kurzinfo werden die Anzahl der Spannen, das Datum und die Uhrzeit sowie das Zeitintervall der Zelle aufgeführt.

     Hinweis :Wenn Sie eine Zelle in der Heatmap auswählen, wird die Tabelle mit den einzelnen Zeiträumen oder Gruppierungen von Zeiträumen aktualisiert.

4. Latenz-Perzentile und Fehlerraten ansehen:

   • Wenn Sie Latenztrends ansehen möchten, stellen Sie das Menü Diagrammansicht auf Spannendauer (Perzentil) ein. Im Dauerdiagramm werden das 50., 90., 95. und 99. Perzentil angezeigt.

   • Wenn Sie den Antwortstatus als Funktion der Zeit sehen möchten, stellen Sie das Menü Diagrammansicht auf Spannenrate ein. Im Diagramm wird die Rate der Spans angezeigt, die an Ihr Projekt gesendet werden.

5. Wenn Sie Ausreißer finden möchten, wählen Sie den Tab Spans (Zeiträume) aus und sortieren Sie die Tabelle nach Dauer.

   Wenn Sie weitere Informationen zu einem bestimmten Zeitraum wünschen, wählen Sie ihn aus. Ein Flyout wird geöffnet, in dem der Span im Kontext seines Traces angezeigt wird. Anschließend können Sie den Bereich und den Trace untersuchen.

6. Wenn Sie die Anzahl der Spans für jeden Dienst sowie statistische Informationen aufrufen möchten, wählen Sie den Tab Gruppiert aus:

   • Jede Zeile bezieht sich auf einen bestimmten Dienst und Span-Namen.
   • Sie können die Zeilen nach der Überschrift „Zeitraum“ sortieren.

   Wenn Sie weitere Informationen zu einer bestimmten Gruppierung aufrufen möchten, wählen Sie den Spannenamen für eine Zeile aus. Ein Flyout wird geöffnet, in dem der Span im Kontext seines Traces angezeigt wird. Anschließend können Sie den Bereich und den Trace untersuchen.

7. Fügen Sie Filter hinzu, um die angezeigten Spans einzuschränken. Weitere Informationen zum Filtern von Trace-Daten finden Sie im nächsten Abschnitt.

Trace-Daten filtern

Wenn Sie nur für Sie relevante Informationen sehen möchten, können Sie Filter anwenden. Mit Filtern wird eingeschränkt, welche Daten angezeigt werden. Sie können beispielsweise nach Dienstname und Status filtern. Wenn Sie Anwendungen in App Hub bereitgestellt haben, möchten Sie die Tracedaten möglicherweise nur für die Anwendung oder für einen bestimmten Dienst oder eine bestimmte Arbeitslast ansehen, die Teil der Anwendung ist.

Wenn Sie einen Filter hinzufügen oder entfernen, werden die Daten, die auf der Seite Trace Explorer angezeigt werden, aktualisiert. Es werden dann nur noch Spans angezeigt, die allen angewendeten Filtern entsprechen.

Nach einem Trace anhand der ID filtern

Wenn Sie einen Vorfall oder Fehler beheben, kennen Sie möglicherweise die Trace-ID. Wenn Sie sich diesen Trace ansehen möchten, klicken Sie in der Symbolleiste auf Seitenaufruf Nach Trace suchen und geben Sie die Trace-ID ein.

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

Hinweis :Wenn Sie eine Trace-ID eingeben, die nicht gefunden wird, sind die Trace-Daten möglicherweise in einem Projekt gespeichert, das nicht auf der Seite Trace Explorer durchsucht wird. Möglicherweise haben Sie auch keine IAM-Rolle, mit der Sie Trace-Daten ansehen können. Um diese Fehler zu beheben, müssen Sie die Projekte identifizieren, in denen die Trace-Daten gespeichert sind. Prüfen Sie für jedes Projekt, ob Sie mit Ihrer IAM-Rolle Tracedaten ansehen können. Achten Sie dann darauf, dass das Element Scope so konfiguriert ist, dass alle Projekte durchsucht werden, in denen Ihre Tracedaten gespeichert sind. Weitere Informationen finden Sie unter Liste der Projekte aktualisieren, in denen nach Trace-Daten gesucht wird.

Zeitraumfilter anwenden

Im Bereich Zeitraumfilter sind die häufigsten Filter aufgeführt. Sie können mehrere Einträge aus einer beliebigen Unterkategorie auswählen. Wenn Sie Filter hinzufügen oder entfernen, wird auch die Filterleiste aktualisiert.

Die Werte für alle Menüs werden aus Ihren Tracedaten abgeleitet. Wenn ein Menü eine Option ohne Text enthält, bezieht sich diese Option auf Spannen, die das entsprechende Attribut nicht enthalten.

Die folgenden Zeitraumfilter sind in der Regel verfügbar:

• OpenTelemetry-Dienst: Filtert nach dem Attribut service.name.
• Span-Name: Name des Spans.
• Span-Status: Der Status der Anfrage. Informationen zu den Werten finden Sie in der OpenTelemetry-Dokumentation zu SpanStatus.
• Dauer: Die Dauer des Zeitraums.
• Span-Art: Beschreibt die Beziehungen zwischen Spans. Informationen zu den Werten finden Sie in der OpenTelemetry-Dokumentation zu SpanKind.
• App Hub-Anwendung: Filtert nach dem gcp.apphub.application.id-Ressourcenattribut.
• App Hub-Dienst: Filtert nach dem gcp.apphub.service.id-Ressourcenattribut.
• App Hub-Arbeitslast: Filtert nach dem Ressourcenattribut gcp.apphub.workload.id.

Wenn Sie nach einem Attribut filtern möchten, das nicht im Bereich Zeitbereichsfilter aufgeführt ist, verwenden Sie die Filterleiste.

Filterleiste verwenden

In der Filterleiste können Sie einen Filter mit einem vordefinierten Filterschlüssel und einem von Ihnen ausgewählten Wert anwenden. Sie können aber auch sowohl den Schlüssel als auch den Wert eingeben.

Wenn Sie einen Filter hinzufügen möchten, wählen Sie Filter hinzufügen aus und gehen Sie dann so vor:

• Wählen Sie einen definierten Schlüssel aus, z. B. Zeitraumname, und dann einen Wert aus dem sekundären Menü.

• Wählen Sie Attributfilter hinzufügen aus und fügen Sie dann Ihren benutzerdefinierten Schlüssel und Wert hinzu. Wenn Sie einen eigenen Filterschlüssel eingeben, verwenden Sie dieselbe Syntax wie für einen Schlüssel für ein Attribut in einem Span.

  Wenn Sie beispielsweise nach der Host-ID filtern möchten, legen Sie den Schlüssel auf host.id fest. Wenn Sie nach Statuscode filtern möchten, legen Sie den Schlüssel auf /http/status_code fest. In diesem Szenario legen Sie den Wert möglicherweise auf 200 fest, was zum Filter /http/status_code: 200 führt. Wenn der Filter mit einem beliebigen Wert übereinstimmen soll, wählen Sie Beliebiger Wert aus.

Nach Anwendung filtern

Trace-Spans, die von Instrumentierungen generiert werden, die Sie Ihren Anwendungen hinzugefügt haben, können die folgenden Ressourcenattribute enthalten:

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

Die Seite Trace-Explorer enthält die folgenden Span-Filter, in deren Menüs Anwendungen, Dienste und Arbeitslasten aufgeführt sind, die in App Hub registriert sind:

• App Hub-Anwendung: Filtert nach dem gcp.apphub.application.id-Ressourcenattribut.
• App Hub-Dienst: Filtert nach dem gcp.apphub.service.id-Ressourcenattribut.
• App Hub-Arbeitslast: Filtert nach dem Ressourcenattribut gcp.apphub.workload.id.

Informationen dazu, wie Sie Ihre Anwendung so instrumentieren, dass Trace-Spans anwendungsspezifische Attribute enthalten, finden Sie unter Für Anwendungsmonitoring instrumentieren.

Trace ansehen

In diesem Abschnitt finden Sie Informationen dazu, wie Sie einen Span im Kontext seines Traces untersuchen können:

1. Öffnen Sie die Seite Trace Explorer und konfigurieren Sie sie. Weitere Informationen zu diesen Schritten finden Sie unter Aggregierte Trace-Daten ansehen.

2. Führen Sie einen der folgenden Schritte aus, um Details zu einem Span oder Trace aufzurufen:

   • Rufen Sie den Tabellenbereich der Seite Trace Explorer auf und wählen Sie einen Eintrag aus dem Tabellenbereich aus. Sie können die Zeilen der Tabellen nach einer beliebigen Tabellenüberschrift sortieren. Sie können Filter anwenden, um einzuschränken, welche Spans in den Tabellen angezeigt werden.

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

   Das Flyout Details wird geöffnet und zeigt einen Trace und seine Spannen an. Die Details für den ausgewählten Span oder Trace werden angezeigt:

   • In der Spalte Name wird die Aufrufhierarchie angezeigt. Der erste Eintrag enthält die Trace-ID. Diese Spalte kann auch Anmerkungen enthalten, die angeben, ob Ereignisse oder Logdaten für generative KI verfügbar sind.
   • Die Spalte Service wird aus dem OpenTelemetry-Attribut service.name extrahiert, wenn dieses Attribut festgelegt ist. Wenn dieses Attribut nicht festgelegt ist und der Dienst in 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 des Latenzbalkens gibt den Status an. Ein blauer Latenzbalken weist auf einen erfolgreichen Abschluss hin, ein roter Latenzbalken auf einen Fehler.
   • Ein Kreis auf einem Latenzbalken gibt an, dass ein Logeintrag oder Ereignis mit dem Zeitraum verknüpft ist. Wenn Sie dieses Verhalten ändern möchten, verwenden Sie das Menü Logs und Ereignisse.

3. So sehen Sie sich den Trace an:

   • Mit dem Mauszeiger können Sie verschiedene Zeiträume auswählen. Wenn Sie einen Bereich auswählen, werden die Tabs auf der Seite aktualisiert, um die Attribute, Logeinträge und Ereignisse des Bereichs anzuzeigen.

   • Wenn Sie in den Spans des Trace nach Keywords suchen möchten, verwenden Sie das Feld Im Trace suchen.

     Die Suche bezieht sich nur auf die Felder „Span-Name“, „Dienstname“ und „Attribute“. Sie können nur nach Nur-Text suchen und nicht nach Logs, Ereignissen oder Metadaten.

     Wenn Sie beispielsweise GET eingeben, wird Text im Spannenname, Dienstname oder im Bereich Attribute, der GET enthält, unabhängig von der Groß-/Kleinschreibung hervorgehoben.

   Hinweis :Im Trace Explorer werden maximal 10.000 Spans für einen Trace angezeigt.

Attribute, Logeinträge und Ereignisse ansehen

Das Flyout Details für einen Zeitraum enthält einen Tab für jede der folgenden Optionen:

• Attribute: Auf diesem Tab werden Labels aufgeführt, die an Spans angehängt sind. Informationen zu Labels finden Sie unter Trace-Labels.

• Logs und Ereignisse: Auf diesem Tab werden Ereignisse und Logeinträge aufgeführt, deren Felder trace_id und span_id mit dem ausgewählten Span übereinstimmen. Es werden nur Logeinträge angezeigt, die Sie aufrufen dürfen.

  Wenn Sie einen Eintrag auf diesem Tab aufrufen möchten, klicken Sie auf  Mehr anzeigen.

  Wenn Sie Logdaten lieber auf der Seite „Log-Explorer“ ansehen möchten, klicken Sie auf Logs ansehen. Die Abfrage ist so konfiguriert, dass sie nach einem bestimmten Trace, Span und Zeitraum filtert.

  Hinweis :Ereignisse im Zusammenhang mit generativer KI werden auf dem Tab Ein-/Ausgaben angezeigt. Weitere Informationen finden Sie unter Ereignisse für generative KI ansehen.

• Stacktraces: Hier werden die verfügbaren Stacktraces aufgeführt.

• Metadaten und Links: Hier werden allgemeine Informationen zum Span aufgeführt:

  • Span-ID: Die Span-ID ist eine 64-Bit-Ganzzahl ungleich 0. Weitere Informationen finden Sie unter TraceSpan.
  • Übergeordnete Span-ID.
  • Projekt-ID.
  • Start- und Endzeit

  • Tabelle mit Links zu anderen Zeiträumen. In dieser Tabelle werden für jeden Link die folgenden Informationen aufgeführt:

    • Die Schlüssel/Wert-Paare für den verknüpften Bereich.
    • Die Trace-ID für den verknüpften Span. Wenn in diesem Feld Aktueller Trace aufgeführt ist, wird der Span mit einem anderen Span im selben Trace verknüpft.

    Informationen zu Links finden Sie auf der API-Referenzseite für Links.

Die Details können auch einen Tab mit dem Label Ein-/Ausgaben enthalten. Auf diesem Tab werden Ereignisse im Zusammenhang mit generativer KI angezeigt.

Ereignisse zu generativer KI ansehen

Vorschau

Diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Wenn Sie Ereignisse im Zusammenhang mit generativen KI-Agents aufrufen möchten, verwenden Sie den Tab Ein-/Ausgaben. Auf diesem Tab werden Ereignisse angezeigt, die den semantischen OpenTelemetry-Konventionen für generative KI entsprechen.

Es gibt zwei unterstützte Konfigurationen:

• Textbasierte Prompts und Antworten, die den Spans als Attribute angehängt werden. Attribute sind Schlüssel/Wert-Paare, die eine bestimmte Eigenschaft oder ein Ereignis beschreiben. Der Wert für den Schlüssel gen_ai.system gibt beispielsweise das System an, das die Funktionen für generative KI bereitstellt. Die Schlüssel für Attribute generativer KI beginnen mit gen_ai.

• Multimodale Prompts und Antworten, die in einem Cloud Storage-Bucket gespeichert sind. Cloud Trace identifiziert diese Ereignisse, indem Ihre Trace- und Logdaten korreliert werden. Informationen zu unterstützten Konfigurationen finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Der folgende Screenshot zeigt, wie auf der Seite Trace Explorer textbasierte generative KI-Ereignisse gerendert werden, die den Spans zugeordnet sind:

Informationen zur Beispielanwendung, mit der der vorherige Screenshot erstellt wurde, finden Sie unter LangGraph ReAct Agent mit OpenTelemetry instrumentieren.

Nächste Schritte

• Trace-Bereiche erstellen und verwalten
• Traces und Spannen teilen
• Fehlerbehebung