Ce document explique comment interroger et analyser vos données de journaux et de traces à 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 votre requête, utilisez le format tabulaire ou visualisez les données à l'aide de graphiques. Vous pouvez également enregistrer ces tableaux et graphiques dans vos tableaux de bord personnalisés.
À 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 journaux, vos données de trace ou les deux types de données lorsque vous utilisez la page Analyse de journaux.
Vous avez besoin d'ensembles de données BigQuery associés lorsque vous souhaitez effectuer l'une des opérations suivantes :
- Associez les données de journaux ou de trace à d'autres ensembles de données BigQuery.
- Interrogez vos données de journaux ou de trace à partir 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.
- Créez une règle d'alerte qui surveille le résultat d'une requête SQL. Cette fonctionnalité n'est disponible que lorsque des données de journaux sont interrogées. Pour en savoir plus, consultez Surveiller les résultats de vos requêtes SQL avec une règle d'alerte.
Ce document ne décrit pas comment créer un ensemble de données associé, ce qui nécessite un processus spécifique au type de données. Pour savoir comment créer un ensemble de données associé, consultez Interroger les données de journaux à l'aide d'un ensemble de données associé ou Interroger les données de trace à l'aide d'un ensemble de données 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Activez l'API Observability.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (
roles/serviceusage.serviceUsageAdmin), qui contient l'autorisationserviceusage.services.enable. Découvrez comment attribuer des rôles. -
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Activez l'API Observability.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (
roles/serviceusage.serviceUsageAdmin), qui contient l'autorisationserviceusage.services.enable. Découvrez comment attribuer des rôles. -
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é. Les vues d'observabilité sont disponibles en version Preview publique. -
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/Logging (
roles/logging.viewer) sur votre projet -
Accesseur de vues de journaux (
roles/logging.viewAccessor) sur le projet qui stocke les vues de journaux que vous souhaitez interroger.
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.
-
Accesseur de vue d'observabilité (
Interroger les données de journaux et de trace
Cette section décrit les approches que vous pouvez utiliser pour interroger vos données de journaux et de traces :
- 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 manage_searchAnalyse 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, sélectionnez une vue.
Pour trouver la vue à interroger, utilisez la barre de filter_list Filtre ou faites défiler la liste :
Les vues de journaux, listées dans la section Journaux, sont classées par ID de bucket et de vue.
Les vues Analytics, listées dans la section Vues Analytics de , sont classées par emplacement et par ID de vue. Les vues d'observabilité sont disponibles en version Preview publique.
Une vue de trace est listée dans la section
Traces. Les vues d'observabilité sont disponibles en version Preview publique.
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 tune 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 code 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 code 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 settings 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 manage_searchAnalyse 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 volet Requête, cliquez sur code 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
WHEREqui spécifie le champtimestamp, 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.
La vue que vous interrogez détermine le format de la clause
FROM:Données des journaux
Vous pouvez interroger les vues de journaux ou les vues d'analyse. Utilisez le format suivant pour la clause
FROM:Vues de journaux :
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`Vues Analytics :
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
Les champs des expressions précédentes ont la signification suivante :
- PROJECT_ID : identifiant du projet.
- LOCATION : emplacement de la vue des journaux ou de la vue des données analytiques.
- BUCKET_ID : nom ou ID du bucket de journaux.
- LOG_VIEW_ID : identifiant de la vue de journal, limité à 100 caractères et ne pouvant inclure que des lettres, des chiffres, des traits de soulignement et des traits d'union.
- ANALYTICS_VIEW_ID : ID de la vue Analytics, limité à 100 caractères et ne pouvant inclure que des lettres, des chiffres, des traits de soulignement et des traits d'union.
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 La clause d'erreurFROMdoit contenir exactement une vue de journal.Données de trace
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 settings 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 manage_searchAnalyse 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.
Si le volet Requête affiche un éditeur SQL, sélectionnez tune 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
FROMdans 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
WHEREdans 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
SELECTde 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
WHEREdans 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 BYdans 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
LIMITde 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 settings 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.
Données des journaux
Cet exemple décrit comment utiliser l'outil de création de requêtes pour regrouper les entrées de journaux par gravité et code temporel, puis calculer la moyenne du champ http_request.response_size pour chaque groupe.
Pour créer une requête qui regroupe et agrège vos données, effectuez les sélections suivantes dans les menus du générateur de requêtes :
Dans le menu Colonnes, sélectionnez les champs
timestamp,severityethttp_request.response_size.Pour regrouper vos données, cliquez sur le champ
timestampafin d'ouvrir la boîte de dialogue des paramètres. Dans cette boîte de dialogue, sélectionnez l'option Grouper par et définissez la précision de troncature surHOUR. Le regroupement est ensuite appliqué automatiquement à tous les autres champs pour éviter les erreurs de syntaxe. Si des champs non valides empêchent le regroupement, un message d'erreur s'affiche. Pour résoudre cette erreur, supprimez les champs non valides du menu.Pour agréger le champ
http_request.response_size, cliquez dessus pour ouvrir la boîte de dialogue des paramètres. Dans cette boîte de dialogue, sélectionnez Agréger. Dans le menu Agrégation, cliquez sur Moyenne.
Dans le menu Filtres, ajoutez
http_request.response_sizeet définissez le comparateur surIS NOT NULL. Ce filtre correspond aux entrées de journal qui contiennent une valeurresponse_size.Les menus du générateur de requêtes ressemblent à ce qui suit :

Pour exécuter la requête, accédez à la barre d'outils et sélectionnez Exécuter la requête.
Les résultats de cette requête sont semblables à ceux-ci :
+-----------------------------------+----------+---------------+ | Row | hour_timestamp | severity | response_size | | | TIMESTAMP | STRING | INTEGER | +-----+-----------------------------+----------+---------------+ | 1 | 2025-10-06 16:00:00.000 UTC | NOTICE | 3082 | | 2 | 2025-10-06 17:00:00.000 UTC | WARNING | 338 | | 3 | 2025-10-06 16:00:00.000 UTC | INFO | 149 |
La requête SQL correspondante pour l'exemple précédent est la suivante :
SELECT
-- Truncate the timestamp by hour.
TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
severity,
-- Compute average response_size.
AVG( http_request.response_size ) AS average_http_request_response_size
FROM
`PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
-- Matches log entries that have a response_size.
http_request.response_size IS NOT NULL
GROUP BY
-- Group log entries by timestamp and severity.
TIMESTAMP_TRUNC( timestamp, HOUR ),
severity
LIMIT
1000
Données de trace
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,kindetduration_nano. - Pour tronquer l'heure de début à l'heure, développez le menu de la colonne
start_timeet 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.409376Votre 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 :
- Dans l'élément Colonnes, cliquez sur Ajouter une colonne.
- Sélectionnez Tous (*).
- 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
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 manage_searchAnalyse 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, sélectionnez une vue.
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 more_vert Options, puis sélectionnez Afficher les infos et la description.
Données des journaux
Pour les vues de journaux, le schéma est fixe et correspond à
LogEntry. Pour les vues analytiques, vous pouvez modifier la requête SQL afin de changer le schéma.Données de trace
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.
Restrictions
Si vous souhaitez interroger plusieurs vues, elles doivent résider au même emplacement. Par exemple, si vous stockez deux vues dans l'emplacement us-east1, une requête peut interroger les deux vues. Vous pouvez également interroger deux vues stockées dans la région multirégionale us. Toutefois, si l'emplacement d'une vue est global, cette vue peut se trouver n'importe où. Par conséquent, les jointures entre deux vues dont l'emplacement est global peuvent échouer.
Pour obtenir la liste des restrictions qui s'appliquent aux données de journaux, consultez Log Analytics : restrictions.
Étapes suivantes
- Représenter les résultats d'une requête SQL sous forme de graphique
- Enregistrer et partager des requêtes
- Exemples de requêtes SQL