Exemples de requêtes SQL pour Trace

Aperçu

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres pré-DG" de la section "Conditions d'utilisation générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document contient des exemples de requêtes qui sont spécifiques à l'interrogation des données de trace stockées dans votre Google Cloud projet.

Compatibilité avec le langage SQL

Les requêtes utilisées dans la page Analyse de journaux sont compatibles avec les fonctions GoogleSQL, à quelques exceptions près.

Les commandes SQL suivantes ne sont pas compatibles avec les requêtes SQL émises à l'aide de la page Analyse de journaux :

• Commandes LDD et LMD
• Fonctions JavaScript définies par l'utilisateur
• Fonctions BigQuery ML
• Variables SQL

Les éléments suivants ne sont compatibles que lorsque vous interrogez un ensemble de données associé à l'aide de s pages BigQuery Studio et Looker Studio, ou à l'aide de l' outil de ligne de commande bq :

• Fonctions JavaScript définies par l'utilisateur
• Fonctions BigQuery ML
• Variables SQL

Bonnes pratiques

Pour définir la période de votre requête, nous vous recommandons d'utiliser le sélecteur de période. Par exemple, pour afficher les données de la semaine dernière, sélectionnez Les 7 derniers jours dans le sélecteur de période. Vous pouvez également utiliser le sélecteur de période pour spécifier une heure de début et de fin, spécifier une heure à afficher et modifier les fuseaux horaires.

Si vous incluez un champ start_time dans la clause WHERE, le paramètre du sélecteur de période n'est pas utilisé. L'exemple suivant filtre les données à l'aide de la fonction TIMESTAMP_SUB, qui vous permet de spécifier un intervalle de rétrospection à partir de l'heure actuelle :

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Pour en savoir plus sur le filtrage par heure, consultez Fonctions temporelles et Fonctions d'horodatage.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

1. Pour obtenir les autorisations nécessaires pour charger la page Analyse de journaux , é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 d'analyse d'observabilité (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.

Utiliser les requêtes de cette page

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

2. Dans le volet Requête, cliquez sur le  SQL, puis copiez et collez une requête dans le volet de requête SQL.

   Voici le format de la clause FROM pour interroger la vue _AllSpans :

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

   La clause FROM contient les champs suivants :

   • PROJECT_ID : identifiant du projet.
   • LOCATION : l'emplacement du bucket d'observabilité.
   • _Trace : nom du bucket d'observabilité.
   • Spans : nom de l'ensemble de données.
   • _AllSpans : nom de la vue.
   Remarque : Les délimiteurs du chemin d'accès sont des points (.) Si un élément de chemin d'accès tel que le projet contient un point, assurez-vous que chaque champ de chemin d'accès est placé entre accents graves simples (`)`).
   Google Cloud (`)

Pour utiliser les requêtes présentées dans ce document sur la page BigQuery Studio ou pour utiliser l'outil de ligne de commande bq, modifiez la clause FROM et saisissez le chemin d'accès à l'ensemble de données associé. Par exemple, pour interroger la _AllSpans vue sur l'ensemble de données associé nommé my_linked_dataset qui se trouve dans le projet myproject, le chemin d'accès est `myproject.my_linked_dataset._AllSpans`.

Cas d'utilisation courants

Cette section répertorie plusieurs cas d'utilisation courants qui peuvent vous aider à créer vos requêtes personnalisées.

Afficher toutes les données de trace

Pour interroger la vue _AllSpans, exécutez la requête suivante :

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

Afficher les informations courantes sur les segments

Pour afficher les informations courantes sur les segments, telles que l'heure de début et la durée, exécutez la requête suivante :

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

Pour en savoir plus, consultez Expressions conditionnelles.

Afficher les 50e et 99e centiles de la latence des segments

Pour afficher les 50e et 99e centiles de la latence de chaque service RPC, exécutez la requête suivante :

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

Pour en savoir plus sur l'énumération, consultez la documentation OpenTelemetry : SpanKind.

Pour afficher les résultats sous forme de graphique, vous pouvez créer un graphique dont la dimension est définie sur rpc_service_method. Vous pouvez ajouter deux mesures, l'une pour la moyenne de la valeur duration_nano_p50 et l'autre pour la moyenne du champ duration_nano_p99.

Filtrer les entrées de trace

Pour appliquer un filtre à votre requête, ajoutez une clause WHERE. La syntaxe que vous utilisez dans cette clause dépend du type de données du champ. Cette section fournit plusieurs exemples pour différents types de données.

Filtrer par types de données de chaîne

Le champ name est stocké sous forme de String.

• Pour n'analyser que les segments où name est spécifié, utilisez la clause suivante :

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• Pour n'analyser que les segments où name a la valeur "POST", utilisez la clause suivante :

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• Pour n'analyser que les segments où name contient la valeur "POST", utilisez l'opérateur LIKE avec des caractères génériques :

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

Filtrer par types de données entiers

Le champ kind est un entier qui peut prendre des valeurs comprises entre zéro et cinq :

• Pour n'analyser que les segments où kind est spécifié, utilisez la clause suivante :

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• Pour analyser les segments dont la valeur kind est égale à 1 ou 2, utilisez la clause suivante :

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

Filtrer par types de données RECORD

Certains champs du schéma de trace ont un type de données RECORD. Ces champs peuvent stocker une ou plusieurs structures de données, ou des entrées répétées de la même structure de données.

Filtrer par état ou code d'état

Le champ status est un exemple de champ dont le type de données est RECORD. Ce champ stocke une structure de données, avec des membres libellés code et message.

• Pour n'analyser que les segments lorsque le champ status.code a la valeur 1, ajoutez la clause suivante :

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  Le champ status.code est stocké sous forme d'entier.

• Pour analyser les segments où le champ status n'est pas EMPTY, ajoutez la clause suivante :

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

Filtrer par événements ou liens

Les champs events et links sont stockés avec un type de données RECORD, mais il s'agit de champs répétés.

• Pour faire correspondre les segments qui comportent au moins un événement, utilisez la clause suivante :

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• Pour faire correspondre les segments qui comportent un événement dont le champ name a la valeur message, utilisez la clause suivante :

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

Filtrer par types de données JSON

Le champ attributes est de type JSON. Chaque attribut individuel est une paire clé/valeur.

• Pour n'analyser que les segments où attributes est spécifié, utilisez la clause suivante :

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• Pour n'analyser que les segments où la clé d'attribut nommée component a la valeur "proxy", utilisez la clause suivante :

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  Vous pouvez également utiliser une instruction LIKE avec des caractères génériques pour effectuer un test de contenu :

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

Regrouper et agréger les données de trace

Cette section explique comment regrouper et agréger des segments. Si vous ne spécifiez pas de regroupement, mais que vous spécifiez une agrégation, un seul résultat est imprimé, car SQL traite toutes les entrées qui satisfont la clause WHERE comme un seul groupe.

Chaque expression SELECT doit être incluse dans les champs de groupe ou être agrégée.

Regrouper les segments par heure de début

Pour regrouper les données par heure de début, utilisez la fonction TIMESTAMP_TRUNC, qui tronque un code temporel à une granularité spécifiée, comme HOUR :

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

Pour en savoir plus, consultez la documentation TIMESTAMP_TRUNC et Fonctions de date et d'heure.

Remarque : Si vous incluez un champ start_time dans la clause WHERE, le paramètre du sélecteur de période n'est pas utilisé.

Compter les segments par code d'état

Pour afficher le nombre de segments avec un code d'état spécifique, exécutez la requête suivante :

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

Si vous remplacez status.code par kind, la requête précédente indique le nombre de segments pour chaque valeur de l'énumération kind. De même, si vous remplacez status.code par name, les résultats de la requête affichent le nombre d'entrées pour chaque nom de segment.

Calculer la durée moyenne de tous les segments

Pour afficher la durée moyenne après avoir regroupé les données de segment par nom de segment, exécutez la requête suivante :

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

Calculer la durée moyenne et les centiles par nom de service

La requête suivante calcule le nombre de segments et diverses statistiques pour chaque service :

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

Recherche dans plusieurs colonnes

Cette section décrit deux approches que vous pouvez utiliser pour effectuer une recherche dans plusieurs colonnes de la vue que vous interrogez :

• Recherches basées sur des jetons : vous spécifiez l'emplacement de la recherche, une requête de recherche, puis vous utilisez la fonction SEARCH. Étant donné que la fonction SEARCH est soumise à des règles spécifiques concernant la recherche dans les données, nous vous recommandons de lire la documentation SEARCH.

• Recherches basées sur des sous-chaînes : vous fournissez l'emplacement de la recherche, un littéral de chaîne, puis vous utilisez la fonction CONTAINS_SUBSTR. Le système effectue un test non sensible à la casse pour déterminer si le littéral de chaîne existe dans une expression. La fonction CONTAINS_SUBSTR renvoie TRUE lorsque le littéral de chaîne existe et FALSE dans le cas contraire. La valeur de la recherche doit être un littéral STRING, mais pas le littéral NULL.

Interroger plusieurs vues

Les instructions de requête analysent une ou plusieurs tables ou expressions, et renvoient des lignes de calculs de résultats. Par exemple, vous pouvez utiliser des instructions de requête pour fusionner les résultats d'instructions SELECT sur différentes tables ou ensembles de données de différentes manières, puis sélectionner les colonnes à partir des données combinées.

Pour joindre des vues, les restrictions suivantes s'appliquent :

1. Les emplacements des vues répondent à l'une des conditions suivantes :

   • Toutes les vues se trouvent au même emplacement.
   • Toutes les vues se trouvent à l'emplacement global ou us.

2. Lorsque les ressources de stockage utilisent des clés de chiffrement gérées par le client (CMEK), l'une des conditions suivantes doit être remplie :

   • Les ressources de stockage qui utilisent des CMEK utilisent la même clé Cloud KMS.
   • Les ressources de stockage qui utilisent des CMEK ont un ancêtre commun, et cet ancêtre spécifie une clé Cloud KMS par défaut qui se trouve au même emplacement que les ressources de stockage.

   Lorsqu'une ou plusieurs ressources de stockage utilisent des CMEK, le système chiffre les données temporaires générées par la jointure avec la clé Cloud KMS commune ou la clé Cloud KMS par défaut de l'ancêtre.

Supposons, par exemple, que vous ayez deux vues qui se trouvent au même emplacement. Vous pouvez ensuite joindre ces vues lorsque l'une des conditions suivantes est remplie :

• Les ressources de stockage n'utilisent pas de CMEK.
• Une ressource de stockage utilise des CMEK et l'autre non.
• Les deux ressources de stockage utilisent des CMEK et la même clé Cloud KMS.

• Les deux ressources de stockage utilisent des CMEK, mais des clés différentes. Toutefois, les ressources partagent un ancêtre qui spécifie une clé Cloud KMS par défaut qui se trouve au même emplacement que les ressources de stockage.

  Supposons, par exemple, que la hiérarchie des ressources d'un bucket de journaux et d'un bucket d'observabilité inclue la même organisation. Vous pouvez joindre des vues sur ces buckets lorsque, pour cette organisation, vous avez configuré les paramètres de ressource par défaut pour Cloud Logging et pour les buckets d'observabilité avec la même clé Cloud KMS par défaut pour l'emplacement de stockage.

Joindre des données de trace et de journal à l'aide de l'ID de trace

La requête suivante joint les données de journal et de trace à l'aide des ID de segment et de trace :

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

La réponse de la requête liste l'ID de trace et de segment, ce qui vous permet de les interroger individuellement pour recueillir plus d'informations. En outre, les résultats indiquent la gravité de l'entrée de journal et la charge utile JSON.

Étape suivante

• Enregistrer et partager une requête SQL.
• Représenter les résultats d'une requête SQL sous forme de graphique.
• Interroger un ensemble de données associé dans BigQuery.

Pour obtenir la documentation de référence SQL ou d'autres exemples, consultez les documents suivants :

• Fonctions, opérateurs et expressions conditionnelles.
• Fonctions de recherche.
• Syntaxe des requêtes.
• Exemples de requêtes SQL pour Cloud Logging.