Interroger et analyser des traces

L'Analyse de l'observabilité vous permet d'exécuter des requêtes SQL sur vos données Cloud Trace pour découvrir des tendances de performances, générer des insights agrégés et visualiser les résultats dans des graphiques et des tableaux. Les requêtes sont exécutées sur la vue _AllSpans par défaut, qui inclut toutes les données de trace stockées par votre projet. Vous pouvez enregistrer vos résultats dans des tableaux de bord personnalisés.

Si vous souhaitez inspecter des traces, des segments ou des attributs de segment individuels, utilisez la page Explorateur Trace. Pour en savoir plus, consultez Rechercher et explorer des traces.

À 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, ou vos données de trace et de journal. Dans ce cas, vous pouvez utiliser la page Analyse de l'observabilité. Pour en savoir plus sur l'interrogation des données de journaux, consultez Interroger et analyser des journaux avec l'Analyse de l'observabilité.

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

Ce document ne décrit pas comment créer un ensemble de données BigQuery associé ni comment configurer l'analyse de l'observabilité pour exécuter des requêtes sur le moteur BigQuery. Pour en savoir plus sur ces sujets, consultez Créer un ensemble de données BigQuery associé et Exécuter des requêtes de trace sur le moteur BigQuery.

Avant de commencer

  1. 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.

  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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

  8. Pour obtenir les autorisations nécessaires pour charger la page Analyse de l'observabilité, é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'attribution à une vue spécifique. Si vous n'associez pas de condition à l'attribution du rôle, le compte principal peut accéder à toutes les vues d'observabilité.
    • Utilisateur de l'analyse de l'observabilité (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.

    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, ce qui inclut 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 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 forme d'entier comme 100 ou de 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 :

  1. Dans la console Google Cloud , accédez à la page Analyse de l'observabilité :

    Accéder à Observability Analytics

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

  2. Dans le menu Vues, accédez à la section Traces, puis sélectionnez _Trace.Spans._AllSpans.

    Le volet Schéma est mis à jour. L'analyse de l'observabilité déduit automatiquement les champs d'une colonne lorsque le type de données est JSON. Pour voir à quelle fréquence ces champs inférés apparaissent 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, cela signifie que votre projetGoogle Cloud ne contient pas de bucket d'observabilité nommé _Trace. Pour en savoir plus sur la résolution de ce problème, consultez Échec de l'initialisation du stockage de 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 options dans le menu, puis exécutez-la. Analyse de l'observabilité convertit vos sélections en une requête SQL que vous pouvez afficher et modifier.

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

  1. Dans la console Google Cloud , accédez à la page Analyse de l'observabilité :

    Accéder à Observability Analytics

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

  2. 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 en savoir plus sur la résolution de ce problème, consultez Échec de l'initialisation du stockage de traces.

  3. Effectuez l'une des opérations suivantes :

    • Pour charger une requête définie par le système qui repose 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  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.

  4. 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 Générateur de requêtes, mais que vous souhaitez afficher la requête SQL, cliquez sur  SQL.

  5. Facultatif : modifiez la requête.

  6. Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

    Analyse de l'observabilité présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Créer un graphique à partir des résultats d'une requête SQL.

    Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer l'Analyse de l'observabilité pour qu'elle 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 :

  1. Dans la console Google Cloud , accédez à la page Analyse de l'observabilité :

    Accéder à Observability Analytics

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

  2. 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 sous la forme suivante :

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

      Les champs de l'expression précédente ont la signification suivante :

      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 en savoir plus sur la résolution de ce problème, consultez Message d'erreur indiquant qu'une vue n'existe pas.

  3. Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

    Analyse de l'observabilité présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Créer un graphique à partir des résultats d'une requête SQL.

    Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer l'Analyse de l'observabilité pour qu'elle 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 des menus. Analyse de l'observabilité convertit vos sélections en une 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 l'observabilité peut toujours convertir vos sélections de menu de l'interface du générateur de requêtes en requête SQL. Cependant, 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 des jointures ne peuvent pas être représentées par cette interface.

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

  1. Dans la console Google Cloud , accédez à la page Analyse de l'observabilité :

    Accéder à Observability Analytics

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

  2. 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.

  3. 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.

  4. Facultatif : utilisez les menus suivants pour limiter ou formater la table de résultats :

    • Rechercher dans tous les champs : recherchez des 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 des 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.

      • Convertit 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 segments contenant un attribut ou un ID de segment spécifique. Le menu liste toutes les options de filtre 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 est 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 la table de résultats. Vos sélections sont mappées à la clause LIMIT dans la requête SQL.

  5. Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.

    Analyse de l'observabilité présente les résultats de la requête dans un tableau. Toutefois, vous pouvez créer un graphique, et enregistrer le tableau ou le graphique dans un tableau de bord personnalisé. Pour en savoir plus, consultez Créer un graphique à partir des résultats d'une requête SQL.

    Si la barre d'outils affiche Exécuter dans BigQuery, vous devez configurer l'Analyse de l'observabilité pour qu'elle 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égation : regroupe les champs listés dans l'élément Colonnes, sauf si le champ comporte une sélection Agrégation. 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.
  • Critère de regroupement : regroupe les entrées par tous les champs listés dans l'élément Columns.

Cet exemple montre comment utiliser le générateur de requêtes pour regrouper les segments par heure de début, nom et type, puis calculer la durée moyenne en nanosecondes pour chaque groupe :

  1. Dans le menu Colonnes, sélectionnez les champs start_time, name, kind et duration_nano.
  2. Pour tronquer l'heure de début à l'heure, développez le menu de la colonne start_time et sélectionnez Critère de regroupement. Assurez-vous que le menu de précision est défini sur Heure.

  3. Cliquez sur Appliquer.

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

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

  4. Développez le menu du champ duration_nano, sélectionnez Agrégation, 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 segment et d'un type de segment. La dernière entrée de chaque ligne correspond à la durée moyenne de toutes les entrées de ce groupe.

    Le résultat de cette requête se présente comme suit :

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duration_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. 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 Agrégation, sélectionnez Nombre pour l'agrégation, puis sélectionnez Appliquer.

    Avec cette modification, le regroupement reste le même. Les entrées sont regroupées par heure de début tronquée, nom de segment et genre 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.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

Étapes suivantes