Interroger et analyser les traces

Ce document explique comment interroger et analyser vos données de trace à l'aide d' Observability Analytics, qui fournit une interface de requête basée sur SQL. SQL vous permet d'effectuer une analyse agrégée, ce qui peut vous aider à générer des insights et à identifier des tendances. Pour afficher les résultats de votre requête, utilisez des tableaux ou des graphiques. Vous pouvez également enregistrer ces tableaux et graphiques dans vos tableaux de bord personnalisés.

Si vous souhaitez afficher ou explorer des traces ou des délais individuels, ou afficher des attributs associés à des délais, utilisez la page Explorateur de traces. Pour en savoir plus sur cette page, consultez Rechercher et explorer des traces.

Pour les traces, vous pouvez interroger un bucket d'observabilité nommé _Trace. Une vue, _AllSpans, est disponible pour les requêtes. Pour en savoir plus sur le stockage de vos données de trace, consultez Présentation du stockage.

À propos des ensembles de données BigQuery associés

Vous n'avez pas besoin d'un ensemble de données BigQuery associé pour interroger vos données de trace, ni pour interroger vos données de trace et de journal. Dans ces cas, vous pouvez utiliser la page Observability Analytics. Pour en savoir plus sur l'interrogation des données de journal, consultez Interroger et analyser des journaux avec Observability Analytics.

Vous avez besoin d'un ensemble de données BigQuery associé lorsque vous souhaitez effectuer l'une des opérations suivantes :

Joindre des données de trace à d'autres ensembles de données BigQuery.
Interroger des données de trace à partir d'un autre service, tel que la page BigQuery Studio ou Looker Studio.
Améliorer les performances des requêtes que vous exécutez à partir de Observability Analytics en les exécutant sur vos emplacements réservés BigQuery.

Ce document ne décrit pas comment créer un ensemble de données associé ni comment configurer Observability Analytics pour exécuter des requêtes sur des emplacements réservés. Pour en savoir plus sur ces sujets, consultez Interroger un ensemble de données BigQuery associé.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

Pour obtenir les autorisations nécessaires pour charger la page Observability Analytics , écrire, exécuter et enregistrer des requêtes privées sur vos données de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants :
- Accesseur de vue d'observabilité (roles/observability.viewAccessor) sur les vues d'observabilité que vous souhaitez interroger. Ce rôle est compatible avec les conditions IAM, qui vous permettent de limiter l'octroi à une vue spécifique. Si vous n'associez pas de condition à l'attribution de rôle, le compte principal peut accéder à toutes les vues d'observabilité.
- Utilisateur Observability Analytics (roles/observability.analyticsUser) sur votre projet. Ce rôle contient les autorisations requises pour enregistrer et exécuter des requêtes privées, ainsi que pour exécuter des requêtes partagées.
- Lecteur de journaux (roles/logging.viewer) sur votre projet.
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Afficher le schéma

Le schéma définit la manière dont les données sont stockées, y compris les champs et leurs types de données. Ces informations sont importantes, car le schéma détermine les champs que vous interrogez et si vous devez convertir des champs en différents types de données. Par exemple, pour écrire une requête qui calcule la latence moyenne des requêtes HTTP, vous devez savoir comment accéder au champ de latence et s'il est stocké sous forme d'entier comme 100 ou sous forme de chaîne comme "100". Si les données de latence sont stockées sous forme de chaîne, la requête doit convertir la valeur en valeur numérique avant de calculer une moyenne.

Pour identifier le schéma, procédez comme suit :

Dans la Google Cloud console, accédez à la Analyse de journaux page :
Accéder à l'Analyse de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Dans le menu Vues, accédez à la section Traces , puis sélectionnez _Trace.Spans._AllSpans.

Le volet Schéma est mis à jour. Observability Analytics déduit automatiquement les champs d'une colonne lorsque le type de données est JSON. Pour afficher la fréquence d'apparition de ces champs déduits dans vos données, cliquez sur Options , puis sélectionnez Afficher les informations et la description.

Pour en savoir plus sur le schéma, consultez Schéma de stockage des données de trace.

Si vous ne voyez pas de vue nommée _Trace.Spans._AllSpans, votre Google Cloud projet ne contient pas de bucket d'observabilité nommé _Trace. Pour savoir comment résoudre ce problème, consultez Échec de l'initialisation du stockage des traces.

Interroger des données de trace

Cette section décrit les approches que vous pouvez utiliser pour interroger vos données de trace :

Chargez une requête définie par le système, modifiez-la, puis exécutez-la.
Saisissez et exécutez une requête personnalisée. Par exemple, vous pouvez coller une requête que vous possédez ou en écrire une. Les requêtes personnalisées peuvent inclure des jointures, des requêtes imbriquées et d'autres instructions SQL complexes. Pour obtenir des exemples, consultez Exemples de requêtes SQL.
Créez une requête en effectuant des sélections dans le menu, puis exécutez-la. Observability Analytics convertit vos sélections en requête SQL, que vous pouvez afficher et modifier.

Charger, modifier et exécuter la requête définie par le système

Dans la Google Cloud console, accédez à la Analyse de journaux page :
Accéder à l'Analyse de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

Remarque : Si une fenêtre de la page Observability Analytics affiche le message "Premiers pas avec Observability Analytics", cliquez sur Fermer dans la fenêtre.
Dans le menu Vues, accédez à la section Traces , puis sélectionnez _Trace.Spans._AllSpans.

Si vous ne voyez pas de vue nommée _Trace.Spans._AllSpans, votre Google Cloud projet ne contient pas de bucket d'observabilité nommé _Trace. Pour savoir comment résoudre ce problème, consultez Échec de l'initialisation du stockage des traces.
Effectuez l'une des opérations suivantes :
- Pour charger une requête définie par le système qui s'appuie sur le générateur de requêtes, qui vous permet de définir la requête à l'aide de sélections de menu, assurez-vous que le volet Requête affiche Générateur de requêtes. Si un éditeur SQL s'affiche, alors cliquez sur Générateur.
- Pour charger une requête définie par le système qui extrait des valeurs JSON, assurez-vous que le volet Requête affiche l'éditeur SQL. Si ce volet affiche Générateur de requêtes, cliquez sur SQL.
Dans le volet Schéma, sélectionnez Requête, puis cliquez sur Écraser.

Le volet Requête affiche une requête définie par le système. Si vous avez sélectionné le Générateur de requêtes mode, mais que vous souhaitez afficher la requête SQL, cliquez sur SQL.
Facultatif : modifiez la requête.
Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

Observability Analytics présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et vous pouvez également enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Représenter les résultats d'une requête SQL sous forme de graphique.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer Observability Analytics pour qu'il utilise le moteur de requête par défaut. Pour effectuer cette modification, dans la barre d'outils du volet Requête, cliquez sur Paramètres , puis sélectionnez Analytics (par défaut).

Saisir et exécuter une requête personnalisée

Pour saisir une requête SQL, procédez comme suit :

Dans la Google Cloud console, accédez à la Analyse de journaux page :
Accéder à l'Analyse de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

Remarque : Si une fenêtre de la page Observability Analytics affiche le message "Premiers pas avec Observability Analytics", cliquez sur Fermer dans la fenêtre.
Dans le volet Requête, cliquez sur SQL.
- Pour spécifier une période, nous vous recommandons d'utiliser le sélecteur de période. Si vous ajoutez une clause WHERE qui spécifie le champ timestamp, cette valeur remplace le paramètre du sélecteur de période, et ce sélecteur est désactivé.
- Pour obtenir des exemples, consultez Exemples de requêtes SQL.
- L'éditeur SQL affiche le nom complet de la vue _Trace.Spans._AllSpans, qui se présente comme suit :
```
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
```
  Les champs de l'expression précédente ont la signification suivante :
  - PROJECT_ID : identifiant du projet.
  - LOCATION : l'emplacement du bucket d'observabilité.
  Si le volet de requête affiche un message d'erreur faisant référence à l'instruction FROM, cela signifie que la vue est introuvable. Pour savoir comment résoudre ce problème, consultez Message d'erreur indiquant qu'une vue n'existe pas.
Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

Observability Analytics présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et vous pouvez également enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Représenter les résultats d'une requête SQL sous forme de graphique.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer Observability Analytics pour qu'il utilise le moteur de requête par défaut. Pour effectuer cette modification, dans la barre d'outils du volet Requête, cliquez sur Paramètres , puis sélectionnez Analytics (par défaut).

Créer, modifier et exécuter une requête

L'interface du générateur de requêtes vous permet de créer une requête en effectuant des sélections dans les menus. Observability Analytics convertit vos sélections en requête SQL, que vous pouvez afficher et modifier. Par exemple, vous pouvez commencer par utiliser l'interface du générateur de requêtes , puis passer à l'éditeur SQL pour affiner votre requête.

Observability Analytics peut toujours convertir vos sélections de menu de l'interface du générateur de requêtes en requête SQL. Toutefois, toutes les requêtes SQL ne peuvent pas être représentées par l'interface du générateur de requêtes. Par exemple, les requêtes avec jointures ne peuvent pas être représentées par cette interface.

Pour créer une requête, procédez comme suit :

Dans la Google Cloud console, accédez à la Analyse de journaux page :
Accéder à l'Analyse de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

Remarque : Si une fenêtre de la page Observability Analytics affiche le message "Premiers pas avec Observability Analytics", cliquez sur Fermer dans la fenêtre.
Si le volet Requête affiche un éditeur SQL, sélectionnez Générateur, ce qui ouvre le volet Générateur de requêtes.
Utilisez le menu Source pour sélectionner la vue que vous souhaitez interroger. Vos sélections sont mappées à la clause FROM de la requête SQL.
Facultatif : utilisez les menus suivants pour limiter ou mettre en forme le tableau de résultats :
- Rechercher dans tous les champs : recherchez les chaînes correspondantes. Vos sélections sont mappées à la clause WHERE de la requête SQL.
- Colonnes : sélectionnez les colonnes qui apparaissent dans le tableau de résultats. Vos sélections sont mappées aux clauses SELECT de la requête SQL.
  
  Lorsque vous sélectionnez un nom de champ dans ce menu, une boîte de dialogue s'ouvre. Dans cette boîte de dialogue, vous pouvez effectuer les opérations suivantes :
  - Utilisez le menu pour agréger ou regrouper vos données.
    
    Pour éviter les erreurs de syntaxe, toute agrégation et tout regroupement que vous appliquez à une colonne sont automatiquement appliqués à d'autres colonnes. Pour obtenir un exemple d'agrégation et de regroupement d'entrées, consultez Regrouper et agréger des données à l'aide du générateur de requêtes.
  - Convertissez une valeur de n'importe quel type en un autre type de données spécifié. Pour en savoir plus, consultez la CAST documentation.
  - Extrayez une sous-chaîne de valeurs à l'aide d'expressions régulières. Pour en savoir plus, consultez la REGEXP_EXTRACT documentation.
- Filtres : ajoutez des filtres lorsque vous souhaitez limiter la requête aux délais qui contiennent un attribut ou un ID de délai spécifique. Le menu liste toutes les options de filtre disponibles. Vos sélections sont mappées à la clause WHERE de la requête SQL.
- Trier par : définissez les colonnes à trier et si le tri est croissant ou décroissant. Vos sélections sont mappées à la clause ORDER BY de la requête SQL.
- Limite : définissez le nombre maximal de lignes dans le tableau de résultats. Vos sélections sont mappées à la clause LIMIT de la requête SQL.
Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

Observability Analytics présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et vous pouvez également enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Représenter les résultats d'une requête SQL sous forme de graphique.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer Observability Analytics pour qu'il utilise le moteur de requête par défaut. Pour effectuer cette modification, dans la barre d'outils du volet Requête, cliquez sur Paramètres , puis sélectionnez Analytics (par défaut).

Exemple : Regrouper et agréger des données à l'aide du générateur de requêtes

Lorsque vous sélectionnez une colonne dans le générateur de requêtes, chaque champ inclut un menu dans lequel vous pouvez ajouter un regroupement et une agrégation. Le regroupement vous permet d'organiser vos données en groupes en fonction de la valeur d'une ou de plusieurs colonnes, et l'agrégation vous permet d'effectuer des calculs sur ces groupes pour renvoyer une seule valeur.

Chaque champ que vous sélectionnez dans l'élément Colonnes est associé à un menu contenant les options suivantes :

Aucun : ne pas regrouper ni agréger par ce champ.
Agréger : regroupez les champs listés dans l'élément Colonnes, sauf lorsque le champ comporte une sélection Agréger. Pour ces champs, calculez la valeur en effectuant une opération sur toutes les entrées de chaque regroupement. L'opération peut consister à calculer la moyenne d'un champ ou à compter le nombre d'entrées dans chaque regroupement.
Grouper par : regroupez les entrées par tous les champs listés dans l'élément Colonnes.

L'exemple suivant illustre comment créer une requête qui regroupe des entrées, puis effectue un type d'agrégation.

Cet exemple explique comment utiliser le générateur de requêtes pour regrouper les délais par heure de début, nom de délai et type de délai. Ensuite, pour chaque groupe, la requête calcule la durée moyenne en nanosecondes.

Pour créer cette requête, procédez comme suit :

Dans le menu Colonnes , sélectionnez les champs start_time, name, kind et duration_nano.
Pour tronquer l'heure de début à l'heure, développez le menu de la colonne start_time et sélectionnez Grouper par. Assurez-vous que le menu de granularité est défini sur Heure.
Cliquez sur Appliquer.

Lorsque vous sélectionnez Grouper par pour une colonne, le système regroupe les entrées par toutes les colonnes. Dans cet exemple, les entrées sont regroupées par la valeur tronquée de start_time, le nom du délai, le type de délai et la valeur de la durée.

Toutefois, l'objectif de cet exemple est de regrouper les entrées par heure tronquée, nom de délai et type de délai, puis de calculer la durée moyenne pour chaque groupe. À l'étape suivante, vous allez modifier le regroupement et ajouter une agrégation.

Développez le menu du champ duration_nano, sélectionnez Agréger, et puis définissez le champ Agrégation sur Moyenne.

Lorsque vous exécutez la requête, chaque ligne correspond à un groupe, qui se compose d'une heure tronquée, d'un nom de délai et d'un type de délai. La dernière entrée de chaque ligne correspond à la durée moyenne de toutes les entrées de ce groupe.

Les résultats de cette requête sont semblables à ceux-ci :

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

Votre requête peut inclure plusieurs agrégations. Par exemple, pour ajouter une colonne qui compte le nombre d'entrées dans chaque groupe, procédez comme suit :
1. Dans l'élément Colonnes, cliquez sur Ajouter une colonne.
2. Sélectionnez Tout (*).
3. Dans la boîte de dialogue, sélectionnez Agréger, sélectionnez Compter pour l' Agrégation, puis sélectionnez Appliquer.
Avec cette modification, le regroupement reste le même. Les entrées sont regroupées par l'heure de début tronquée, le nom du délai et le type de délai. Toutefois, pour chaque groupe, la requête calcule la durée moyenne et le nombre d'entrées.

La requête SQL correspondante pour l'exemple précédent est la suivante :

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._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