Traces abfragen und analysieren

In diesem Dokument wird beschrieben, wie Sie Ihre Trace-Daten mit Observability Analytics abfragen und analysieren. Observability Analytics bietet eine SQL-basierte Abfrageschnittstelle. Mit SQL können Sie Aggregatanalysen durchführen, mit denen Sie Erkenntnisse gewinnen und Trends erkennen können. Sie können sich die Abfrageergebnisse in Tabellen oder Diagrammen ansehen. Sie können diese Tabellen und Diagramme auch in Ihren benutzerdefinierten Dashboards speichern.

Wenn Sie einzelne Traces oder Spans ansehen oder untersuchen oder Attribute aufrufen möchten, die an Spans angehängt sind, verwenden Sie die Seite Trace Explorer. Weitere Informationen zu dieser Seite finden Sie unter Traces suchen und untersuchen.

Für Traces können Sie einen Observability-Bucket mit dem Namen _Trace abfragen. Es ist eine Ansicht, _AllSpans, für Abfragen verfügbar. Weitere Informationen zum Speichern von Trace-Daten finden Sie unter Speicherübersicht.

Verknüpfte BigQuery-Datasets

Sie benötigen kein verknüpftes BigQuery-Dataset, um Ihre Trace-Daten oder Ihre Trace- und Logdaten abzufragen. In diesen Fällen können Sie die Seite Observability Analytics verwenden. Informationen zum Abfragen von Logdaten finden Sie unter Logs mit Observability Analytics abfragen und analysieren.

Sie benötigen ein verknüpftes BigQuery-Dataset, wenn Sie eine der folgenden Aktionen ausführen möchten:

In diesem Dokument wird nicht beschrieben, wie Sie ein verknüpftes BigQuery-Dataset erstellen oder Observability Analytics so konfigurieren, dass Abfragen in reservierten Slots ausgeführt werden. Weitere Informationen zu diesen Themen finden Sie unter Verknüpftes BigQuery-Dataset abfragen.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Laden der Seite Observability Analytics und zum Schreiben, Ausführen und Speichern privater Abfragen für Ihre Trace-Daten benötigen:

    • Observability View Accessor (roles/observability.viewAccessor) für die Observability-Ansichten, die Sie abfragen möchten. Diese Rolle unterstützt IAM-Bedingungen, mit denen Sie die Zuweisung auf eine bestimmte Ansicht beschränken können. Wenn Sie der Rollenzuweisung keine Bedingung hinzufügen, kann das Hauptkonto auf alle Observability-Ansichten zugreifen.
    • Observability Analytics-Nutzer (roles/observability.analyticsUser) für Ihr Projekt. Diese Rolle enthält die Berechtigungen, die zum Speichern und Ausführen privater Abfragen und zum Ausführen freigegebener Abfragen erforderlich sind.
    • Loganzeige (roles/logging.viewer) für Ihr Projekt.

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Schema anzeigen

Das Schema definiert, wie die Daten gespeichert werden, einschließlich der Felder und ihrer Datentypen. Diese Informationen sind wichtig, da das Schema die Felder bestimmt, die Sie abfragen, und ob Sie Felder in andere Datentypen umwandeln müssen. Wenn Sie beispielsweise eine Abfrage schreiben möchten, mit der die durchschnittliche Latenz von HTTP-Anfragen berechnet wird, müssen Sie wissen, wie Sie auf das Latenzfeld zugreifen und ob es als Ganzzahl wie 100 oder als String wie "100" gespeichert ist. Wenn die Latenzdaten als String gespeichert sind, muss die Abfrage den Wert in einen numerischen Wert umwandeln, bevor ein Durchschnitt berechnet werden kann.

So rufen Sie das Schema auf:

  1. Rufen Sie in der Google Cloud Console die Observability Analytics Seite auf:

    Zu Observability Analytics

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

  2. Gehen Sie im Menü Ansichten zum Abschnitt Traces und wählen Sie dann _Trace.Spans._AllSpans aus.

    Der Bereich Schema wird aktualisiert. Observability Analytics leitet die Felder einer Spalte automatisch ab, wenn der Datentyp JSON ist. Wenn Sie sehen möchten, wie oft diese abgeleiteten Felder in Ihren Daten vorkommen, klicken Sie auf Optionen und wählen Sie Informationen und Beschreibung ansehen aus.

    Weitere Informationen zum Schema finden Sie unter Speicherschema für Trace-Daten.

    Wenn Sie keine Ansicht mit dem Namen _Trace.Spans._AllSpans sehen, enthält Ihr Google Cloud Projekt keinen Observability-Bucket mit dem Namen _Trace. Informationen zur Behebung dieses Fehlers finden Sie unter Fehler bei der Initialisierung des Trace-Speichers.

Trace-Daten abfragen

In diesem Abschnitt werden die Ansätze beschrieben, mit denen Sie Ihre Trace-Daten abfragen können:

  • Laden Sie eine vom System definierte Abfrage, bearbeiten Sie sie und führen Sie sie dann aus.
  • Geben Sie eine benutzerdefinierte Abfrage ein und führen Sie sie aus. Sie können beispielsweise eine vorhandene Abfrage einfügen oder eine neue schreiben. Benutzerdefinierte Abfragen können Verknüpfungen, verschachtelte Abfragen und andere komplexe SQL-Anweisungen enthalten. Beispiele finden Sie unter SQL-Beispielabfragen.
  • Erstellen Sie eine Abfrage, indem Sie Menüauswahlen treffen, und führen Sie sie dann aus. Observability Analytics konvertiert Ihre Auswahl in eine SQL-Abfrage, die Sie sich ansehen und bearbeiten können.

Vom System definierte Abfrage laden, bearbeiten und ausführen

  1. Rufen Sie in der Google Cloud Console die Observability Analytics Seite auf:

    Zu Observability Analytics

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

  2. Gehen Sie im Menü Ansichten zum Abschnitt Traces und wählen Sie dann _Trace.Spans._AllSpans aus.

    Wenn Sie keine Ansicht mit dem Namen _Trace.Spans._AllSpans sehen, enthält Ihr Google Cloud Projekt keinen Observability-Bucket mit dem Namen _Trace. Informationen zur Behebung dieses Fehlers finden Sie unter Fehler bei der Initialisierung des Trace-Speichers.

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

    • Wenn Sie eine vom System definierte Abfrage laden möchten, die auf dem Query Builder basiert, mit dem Sie die Abfrage über Menüauswahlen definieren können, muss im Bereich Abfrage die Option Query Builder angezeigt werden. Wenn ein SQL-Editor angezeigt wird, dann klicken Sie auf  Builder.

    • Wenn Sie eine vom System definierte Abfrage laden möchten, mit der JSON-Werte extrahiert werden, muss im Bereich Abfrage der SQL-Editor angezeigt werden. Wenn in diesem Bereich Query Builder angezeigt wird, klicken Sie auf  SQL.

  4. Wählen Sie im Bereich Schema die Option Abfrage aus und klicken Sie dann auf Überschreiben.

    Im Bereich Abfrage wird eine vom System definierte Abfrage angezeigt. Wenn Sie den Query Builder Modus ausgewählt haben, aber die SQL-Abfrage sehen möchten, klicken Sie auf  SQL.

  5. Optional: Ändern Sie die Abfrage.

  6. Wenn Sie die Abfrage ausführen möchten, wählen Sie in der Symbolleiste Abfrage ausführen aus.

    Observability Analytics präsentiert die Abfrageergebnisse in einer Tabelle. Sie können jedoch auch ein Diagramm erstellen und die Tabelle oder das Diagramm in einem benutzerdefinierten Dashboard speichern. Weitere Informationen finden Sie unter SQL-SQL-Abfrage darstellen.

    Wenn in der Symbolleiste In BigQuery ausführen angezeigt wird, müssen Sie Observability Analytics so umstellen, dass die Standardabfrage-Engine verwendet wird. Klicken Sie dazu in der Symbolleiste des Abfrage-Bereichs auf Einstellungen und wählen Sie dann Analytics (Standard) aus.

Benutzerdefinierte Abfrage eingeben und ausführen

So geben Sie eine SQL-Abfrage ein:

  1. Rufen Sie in der Google Cloud Console die Observability Analytics Seite auf:

    Zu Observability Analytics

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

  2. Klicken Sie im Bereich Abfrage auf  SQL.

    • Wir empfehlen, den Zeitraum über die Zeitraumauswahl festzulegen. Wenn Sie eine WHERE-Klausel hinzufügen, die das Feld timestamp angibt, überschreibt dieser Wert die Einstellung in der Zeitraumauswahl und die Auswahl wird deaktiviert.

    • Beispiele finden Sie unter SQL-Beispielabfragen.

    • Im SQL-Editor wird der voll qualifizierte Name für die Ansicht _Trace.Spans._AllSpans angezeigt, der die folgende Form hat:

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

      Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

      Wenn im Bereich „Abfrage“ eine Fehlermeldung angezeigt wird, die auf die FROM-Anweisung verweist, kann die Ansicht nicht gefunden werden. Informationen zur Behebung dieses Fehlers finden Sie unter Fehlermeldung, dass eine Ansicht nicht vorhanden ist.

  3. Wenn Sie die Abfrage ausführen möchten, wählen Sie in der Symbolleiste Abfrage ausführen aus.

    Observability Analytics präsentiert die Abfrageergebnisse in einer Tabelle. Sie können jedoch auch ein Diagramm erstellen und die Tabelle oder das Diagramm in einem benutzerdefinierten Dashboard speichern. Weitere Informationen finden Sie unter SQL-SQL-Abfrage darstellen.

    Wenn in der Symbolleiste In BigQuery ausführen angezeigt wird, müssen Sie Observability Analytics so umstellen, dass die Standardabfrage-Engine verwendet wird. Klicken Sie dazu in der Symbolleiste des Abfrage-Bereichs auf Einstellungen und wählen Sie dann Analytics (Standard) aus.

Abfrage erstellen, bearbeiten und ausführen

Mit der Benutzeroberfläche des Query Builder können Sie eine Abfrage erstellen, indem Sie Menüauswahlen treffen. Observability Analytics konvertiert Ihre Auswahl in eine SQL-Abfrage, die Sie sich ansehen und bearbeiten können. Sie können beispielsweise zuerst die Benutzeroberfläche des Query Builder verwenden und dann zum SQL-Editor wechseln, um die Abfrage zu verfeinern.

Observability Analytics kann Ihre Menüauswahlen von der Benutzeroberfläche des Query Builder immer in eine SQL-Abfrage konvertieren. Allerdings können nicht alle SQL-Abfragen durch die Benutzeroberfläche des Query Builder dargestellt werden. Abfragen mit Verknüpfungen können beispielsweise nicht durch diese Benutzeroberfläche dargestellt werden.

So erstellen Sie eine Abfrage:

  1. Rufen Sie in der Google Cloud Console die Observability Analytics Seite auf:

    Zu Observability Analytics

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

  2. Wenn im Bereich Abfrage ein SQL-Editor angezeigt wird, wählen Sie Builder aus, um den Bereich Query Builder zu öffnen.

  3. Wählen Sie im Menü Quelle die Ansicht aus, die Sie abfragen möchten. Ihre Auswahl wird der FROM-Klausel in der SQL-Abfrage zugeordnet.

  4. Optional: Mit den folgenden Menüs können Sie die Ergebnistabelle einschränken oder formatieren:

    • In allen Feldern suchen: Suchen Sie nach übereinstimmenden Strings. Ihre Auswahl wird der WHERE-Klausel in der SQL-Abfrage zugeordnet.

    • Spalten: Wählen Sie die Spalten aus, die in der Ergebnistabelle angezeigt werden sollen. Ihre Auswahl wird den SELECT-Klauseln in der SQL-Abfrage zugeordnet.

      Wenn Sie in diesem Menü einen Feldnamen auswählen, wird ein Dialogfeld geöffnet. In diesem Dialogfeld können Sie Folgendes tun:

      • Verwenden Sie das Menü, um Ihre Daten zu aggregieren oder zu gruppieren.

        Um Syntaxfehler zu vermeiden, werden alle Aggregationen und Gruppierungen, die Sie auf eine Spalte anwenden, automatisch auch auf andere Spalten angewendet. Ein Beispiel für das Aggregieren und Gruppieren von Einträgen finden Sie unter Daten mit dem Query Builder gruppieren und aggregieren.

      • Wandeln Sie einen Wert eines beliebigen Typs in einen anderen angegebenen Datentyp um. Weitere Informationen finden Sie in der CAST Dokumentation.

      • Extrahieren Sie einen Teilstring von Werten mithilfe regulärer Ausdrücke. Weitere Informationen finden Sie in der REGEXP_EXTRACT Dokumentation.

    • Filter: Fügen Sie Filter hinzu, wenn Sie die Abfrage auf Spans beschränken möchten, die ein bestimmtes Attribut oder eine bestimmte Span-ID enthalten. Im Menü sind alle verfügbaren Filteroptionen aufgeführt. Ihre Auswahl wird der WHERE-Klausel in der SQL-Abfrage zugeordnet.

    • Sortieren nach: Legen Sie die Spalten fest, nach denen sortiert werden soll, und ob die Sortierung aufsteigend oder absteigend sein soll. Ihre Auswahl wird der ORDER BY-Klausel in der SQL-Abfrage zugeordnet.

    • Limit: Legen Sie die maximale Anzahl von Zeilen in der Ergebnistabelle fest. Ihre Auswahl wird der LIMIT-Klausel in der SQL-Abfrage zugeordnet.

  5. Wenn Sie die Abfrage ausführen möchten, wählen Sie in der Symbolleiste Abfrage ausführen aus.

    Observability Analytics präsentiert die Abfrageergebnisse in einer Tabelle. Sie können jedoch auch ein Diagramm erstellen und die Tabelle oder das Diagramm in einem benutzerdefinierten Dashboard speichern. Weitere Informationen finden Sie unter SQL-SQL-Abfrage darstellen.

    Wenn in der Symbolleiste In BigQuery ausführen angezeigt wird, müssen Sie Observability Analytics so umstellen, dass die Standardabfrage-Engine verwendet wird. Klicken Sie dazu in der Symbolleiste des Abfrage-Bereichs auf Einstellungen und wählen Sie dann Analytics (Standard) aus.

Beispiel: Daten mit dem Query Builder gruppieren und aggregieren

Wenn Sie im Query Builder eine Spalte auswählen, enthält jedes Feld ein Menü, in dem Sie Gruppierungen und Aggregationen hinzufügen können. Mit der Gruppierung können Sie Ihre Daten anhand des Werts einer oder mehrerer Spalten in Gruppen organisieren. Mit der Aggregation können Sie Berechnungen für diese Gruppen durchführen, um einen einzelnen Wert zurückzugeben.

Jedes Feld, das Sie im Element Spalten auswählen, hat ein angehängtes Menü mit den folgenden Optionen:

  • Keine: Nicht nach diesem Feld gruppieren oder aggregieren.
  • Aggregieren: Gruppieren Sie die Felder, die im Element Spalten aufgeführt sind, es sei denn, für das Feld ist Aggregieren ausgewählt. Für diese Felder wird der Wert berechnet, indem eine Operation für alle Einträge in jeder Gruppierung ausgeführt wird. Die Operation kann beispielsweise darin bestehen, den Durchschnitt eines Felds zu berechnen oder die Anzahl der Einträge in jeder Gruppierung zu zählen.
  • Gruppieren nach: Gruppieren Sie Einträge nach allen Feldern, die im Element Spalten aufgeführt sind.

In diesem Beispiel wird gezeigt, wie Sie mit dem Query Builder Spans nach Startzeit, Spanname und Span-Art gruppieren und dann die durchschnittliche Dauer in Nanosekunden für jede Gruppe berechnen:

  1. Wählen Sie im Menü Spalten die Felder start_time, name, kind und duration_nano aus.
  2. Wenn Sie die Startzeit auf die Stunde kürzen möchten, maximieren Sie das Menü in der Spalte start_time und wählen Sie Gruppieren nach aus. Das Menü für die Granularität muss auf Stunde festgelegt sein.

  3. Klicken Sie auf Übernehmen.

    Wenn Sie für eine Spalte Gruppieren nach auswählen, werden die Einträge nach allen Spalten gruppiert. In diesem Beispiel werden die Einträge nach dem gekürzten Wert von start_time, dem Spannamen, der Span-Art und dem Wert der Dauer gruppiert.

    Ziel dieses Beispiels ist es jedoch, Einträge nach der gekürzten Zeit, dem Spannamen und der Span-Art zu gruppieren und dann für jede Gruppe die durchschnittliche Dauer zu berechnen. Im nächsten Schritt ändern Sie die Gruppierung und fügen eine Aggregation hinzu.

  4. Maximieren Sie das Menü für das Feld duration_nano, wählen Sie Aggregieren aus und legen Sie dann das Feld Aggregation auf Durchschnitt fest.

    Wenn Sie die Abfrage ausführen, entspricht jede Zeile einer Gruppe, die aus einer gekürzten Zeit, einem Spannamen und einer Span-Art besteht. Der letzte Eintrag in jeder Zeile ist die durchschnittliche Dauer für alle Einträge in dieser Gruppe.

    Die Ergebnisse dieser Abfrage sehen in etwa so aus:

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
|     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
+-----+-----------------------------+-----------+---------------+-----------------------+
| 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
| 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
| 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376

  5. Ihre Abfrage kann mehrere Aggregationen enthalten. So fügen Sie beispielsweise eine Spalte hinzu, in der die Anzahl der Einträge in jeder Gruppe gezählt wird:

    1. Klicken Sie im Element Spalten auf Spalte hinzufügen.
    2. Wählen Sie Alle (*) aus.
    3. Wählen Sie im Dialogfeld Aggregieren und für die Aggregation die Option Anzahl aus und klicken Sie dann auf Übernehmen.

    Mit dieser Änderung bleibt die Gruppierung gleich. Die Einträge werden nach der gekürzten Startzeit, dem Spannamen und der Span-Art gruppiert. Für jede Gruppe berechnet die Abfrage jedoch die durchschnittliche Dauer und die Anzahl der Einträge.

Die entsprechende SQL-Abfrage für das vorherige Beispiel sieht so aus:

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.us._Trace.Spans._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

Nächste Schritte