Interroger et analyser les traces

Ce document explique comment interroger et analyser vos données de trace à l'aide de l'analyse de journaux, 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 vos requêtes, 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 spans individuels, ou afficher les attributs associés aux spans, utilisez la page Explorateur Trace. 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 journaux. Dans ces cas, vous pouvez utiliser la page Analyse de journaux. Pour en savoir plus sur l'interrogation des données de journaux, consultez Interroger et analyser des journaux avec l'Analyse de journaux.

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

Joignez les données de trace à d'autres ensembles de données BigQuery.
Interrogez les données de trace d'un autre service, comme la page BigQuery Studio ou Looker Studio.
Améliorez les performances des requêtes que vous exécutez à partir de l'analyse de journaux en les exécutant sur vos emplacements réservés BigQuery.

Ce document n'explique pas comment créer un ensemble de données associé ni comment configurer Log 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 compte Google Cloud . 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 Log 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'accès à 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, et 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 façon dont les données sont stockées, y compris les champs et leurs types de données. Ces informations sont importantes pour vous, car le schéma détermine les champs que vous interrogez et si vous devez caster des champs vers 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 la forme d'un entier comme 100 ou d'une chaîne comme "100". Si les données de latence sont stockées sous forme de chaîne, la requête doit caster la valeur en valeur numérique avant de calculer une moyenne.

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

Dans la console Google Cloud , accédez à la page Analyse de journaux :
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. Log Analytics déduit automatiquement les champs d'une colonne lorsque le type de données est JSON. Pour savoir à quelle fréquence ces champs inférés apparaissent dans vos données, cliquez sur Options, puis sélectionnez Afficher les infos 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, cela signifie que votre projetGoogle Cloud ne contient pas de bucket d'observabilité nommé _Trace. Pour savoir comment résoudre cet échec, consultez Échec de l'initialisation du stockage des traces.

Interroger les 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 avez 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 sélectionnant des éléments dans les menus, puis exécutez-la. L'Analyse de journaux 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 console Google Cloud , accédez à la page Analyse de journaux :
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 Analyse de journaux affiche le message "Commencer à utiliser l'analyse de journaux", 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, cela signifie que votre projetGoogle Cloud ne contient pas de bucket d'observabilité nommé _Trace. Pour savoir comment résoudre cet échec, 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, cliquez sur Concepteur.
- 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 Éditeur de requête, 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 mode Créateur de requêtes, 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.

Log 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 de requêtes SQL sous forme de graphiques.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez passer à Log Analytics pour utiliser 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 console Google Cloud , accédez à la page Analyse de journaux :
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 Analyse de journaux affiche le message "Commencer à utiliser l'analyse de journaux", cliquez sur Fermer dans la fenêtre.
Dans le volet Requête, cliquez sur SQL.
- Pour spécifier une plage de dates, nous vous recommandons d'utiliser le sélecteur de plage de dates. Si vous ajoutez une clause WHERE qui spécifie le champ timestamp, cette valeur remplace le paramètre du sélecteur de période, qui est alors 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 : 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 cet échec, 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.

Log 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 de requêtes SQL sous forme de graphiques.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez passer à Log Analytics pour utiliser 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. L'analyse de journaux 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.

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

Pour créer une requête :

Dans la console Google Cloud , accédez à la page Analyse de journaux :
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 Analyse de journaux affiche le message "Commencer à utiliser l'analyse de journaux", 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 dans 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 dans la requête SQL.
- Colonnes : sélectionnez les colonnes qui s'affichent 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 aux 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 documentation CAST.
  - Extrayez une sous-chaîne de valeurs à l'aide d'expressions régulières. Pour en savoir plus, consultez la documentation REGEXP_EXTRACT.
- Filtres : ajoutez des filtres lorsque vous souhaitez limiter la requête aux portées contenant un attribut ou un ID de portée spécifique. Le menu liste toutes les options de filtrage disponibles. Vos sélections sont mappées à la clause WHERE dans la requête SQL.
- Trier par : définissez les colonnes à trier et indiquez si le tri doit être croissant ou décroissant. Vos sélections sont mappées à la clause ORDER BY dans 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.

Log 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 de requêtes SQL sous forme de graphiques.

Si la barre d'outils affiche Exécuter dans BigQuery, vous devez passer à Log Analytics pour utiliser 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 des regroupements et des agrégations. Le regroupement vous permet d'organiser vos données en groupes en fonction de la valeur d'une ou de plusieurs colonnes. 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 comportant les options suivantes :

Aucun : ne pas regrouper ni agréger par ce champ.
Agréger : regroupe les champs listés dans l'élément Colonnes, sauf si le champ a 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 groupe.
Regrouper par : regroupez les entrées par tous les champs listés dans l'élément Colonnes.

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

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

Pour construire 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 précision 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 de la portée, le type de portée 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 span et type de span, 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, 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 portée et d'un type de portée. 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 Tous (*).
3. Dans la boîte de dialogue, sélectionnez Aggregate (Agrégat), puis Count (Nombre) pour Aggregation (Agrégation), puis Apply (Appliquer).
Avec ce changement, le regroupement reste le même. Les entrées sont regroupées par heure de début tronquée, nom de segment et type de segment. 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