Représenter les résultats d'une requête SQL sous forme de graphique

Ce document explique comment représenter graphiquement les résultats de vos requêtes Observability Analytics, ce qui vous permet d'identifier des tendances et des schémas dans vos données de journaux. Observability Analytics vous permet de rechercher et d'agréger des journaux pour générer des insights utiles à l'aide de requêtes SQL.

Une fois que vous avez exécuté une requête, vous pouvez afficher ses résultats dans un tableau ou les convertir en graphique. Vous pouvez également enregistrer la requête et sa visualisation dans un tableau de bord. Par exemple, pour voir les types de gravité que vos journaux génèrent, créez un graphique qui affiche le nombre de journaux générés au cours des 12 dernières heures et répartissez-les par severity. La capture d'écran suivante illustre des points de données répartis en différents types de gravité :

Avant de commencer

Cette section décrit les étapes que vous devez suivre pour pouvoir utiliser Observability Analytics.

Configurer des buckets de journaux

Assurez-vous que vos buckets de journaux ont été mis à niveau pour utiliser Observability Analytics :

1. Dans la Google Cloud console, accédez à la page Stockage des journaux :

   Accéder à Stockage des journaux

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

2. Pour chaque bucket de journaux comportant une vue de journaux que vous souhaitez interroger, assurez-vous que la Observability Analytics available (Observability Analytics disponible) affiche Open (Ouvrir). Si Upgrade (Mettre à niveau) s'affiche, cliquez sur Upgrade (Mettre à niveau) et suivez les instructions de la boîte de dialogue.

Configurer des rôles et des autorisations IAM

Cette section décrit les rôles ou les autorisations IAM requis pour utiliser Observability Analytics :

• Pour obtenir les autorisations nécessaires pour utiliser Observability Analytics et interroger des vues de journaux, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

  • Pour interroger les buckets de journaux _Required et _Default : Lecteur de journaux (roles/logging.viewer)
  • Pour interroger toutes les vues de journaux d'un projet : Accesseur de vues de journaux (roles/logging.viewAccessor)

  Vous pouvez limiter un principal à une vue de journaux spécifique en ajoutant une condition IAM à l'attribution du rôle Accesseur de vues de journaux effectuée au niveau du projet ou en ajoutant une liaison IAM au fichier de stratégie de la vue de journaux. Pour en savoir plus, consultez Contrôler l'accès à une vue de journaux.

  Il s'agit des mêmes autorisations que celles dont vous avez besoin pour afficher les entrées de journal sur la page Explorateur de journaux. Pour en savoir plus sur les rôles supplémentaires dont vous avez besoin pour interroger des vues sur des buckets définis par l'utilisateur ou pour interroger la vue _AllLogs du bucket de journaux _Default, consultez Rôles Cloud Logging.

• Pour obtenir les autorisations nécessaires pour interroger des vues d'analyse, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Observability Analytics (roles/observability.analyticsUser) sur votre projet.

• Pour obtenir les autorisations nécessaires pour créer des graphiques, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Monitoring (roles/monitoring.editor) sur votre projet.

Sélectionner les données à représenter graphiquement

Pour configurer les données à afficher dans un graphique, créez une requête à l'aide de SQL. Lorsque vous sélectionnez l'onglet Graphique, un graphique affiche les résultats de votre requête. Une fois que vous avez exécuté la requête et généré un graphique, vous pouvez le personnaliser en modifiant son type et en sélectionnant les colonnes à afficher.

Pour afficher les résultats de votre requête sous forme de graphique, exécutez une requête en procédant comme suit :

1. Dans la Google Cloud console, accédez à la page Observability Analytics :

   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 , saisissez une requête, puis cliquez sur Exécuter.

3. Une fois la requête terminée, dans l'onglet Résultats, sélectionnez le mode d'affichage des résultats de votre requête :

   • Table : format tabulaire uniquement.

   • Graphique : format graphique uniquement.

   • Les deux : format graphique et tabulaire.

     Après avoir sélectionné le mode d'affichage des résultats de votre requête, vous pouvez configurer les champs de la visualisation sélectionnée, puis enregistrer la requête et les résultats dans un tableau de bord personnalisé. Le format enregistré est tabulaire lorsque vous avez sélectionné l'option Table. Sinon, le format est un graphique.

     Pour les graphiques, les options de visualisation vous permettent de sélectionner le type de graphique, ainsi que les lignes et les colonnes à représenter graphiquement. Pour en savoir plus sur la configuration des graphiques, consultez Personnaliser la configuration des graphiques.

Personnaliser la configuration des graphiques

Vous pouvez personnaliser la configuration des graphiques en modifiant leur type, en sélectionnant la dimension et la mesure à représenter graphiquement, et en appliquant une répartition. La dimension permet de regrouper ou de catégoriser les lignes. Il s'agit de la valeur de l'axe X. La mesure, ou valeur de l'axe Y, est une série de données représentée sur l' axe Y.

Modifier le type de graphique

Vous pouvez choisir parmi les types de graphiques suivants, en fonction du type de lignes et de colonnes que vous avez sélectionné comme dimension et mesure, et de la manière dont vous souhaitez visualiser ces données.

• Graphique à barres (par défaut) : les graphiques à barres représentent les données sur deux axes. Si votre graphique utilise une catégorie ou une chaîne comme dimension, vous pouvez définir la configuration du graphique à barres sur horizontal ou vertical, où les axes de dimension et de mesure sont inversés.

• Graphique en courbes : les graphiques en courbes peuvent être utilisés pour afficher les modifications des données au fil du temps. Lorsque vous utilisez un graphique en courbes, chaque série temporelle est représentée par une ligne différente qui correspond à la ou aux mesures que vous avez sélectionnées.

  Si votre axe X est basé sur le temps, chaque point de données est placé au début d'un intervalle de temps. Chaque point de données est connecté par une interpolation linéaire.

• Graphique en aires empilées : un graphique en aires est basé sur un graphique en courbes, et la zone située sous chaque ligne est ombrée. Dans les graphiques en aires, les séries de données sont empilées. Par exemple, si vous avez deux séries identiques, elles se chevauchent dans un graphique en courbes, mais la zone ombrée est empilée dans un graphique en aires.

• Graphique à secteurs ou en anneau : un graphique à secteurs montre comment les catégories d'un ensemble de données sont liées à l'ensemble de l'ensemble de données, en utilisant un cercle pour représenter l'ensemble de l'ensemble de données et des secteurs dans le cercle pour représenter les catégories de l'ensemble de données. La taille d'un secteur indique la part, souvent exprimée en pourcentage, de la catégorie dans l'ensemble.

• Tableau : un tableau affiche une ligne pour chaque ligne du résultat de la requête. Les colonnes du tableau sont définies par la clause SELECT. Si vous prévoyez d'afficher des données sous forme de tableau dans un tableau de bord, utilisez une clause LIMIT pour limiter le nombre de lignes du résultat à quelques centaines.

• Jauge ou tableau de données : les jauges et les tableaux de données vous fournissent la valeur la plus récente, ainsi qu'une indication verte, orange ou rouge en fonction de la comparaison de cette valeur à un ensemble de seuils. Contrairement aux jauges, qui n'affichent que des informations sur la valeur la plus récente, les tableaux de données peuvent également inclure des informations sur les valeurs passées.

  Les jauges et les tableaux de données ne peuvent afficher le résultat de la requête que si celui-ci contient au moins une ligne, et que cette ligne contient une colonne avec un horodatage et une colonne avec des données numériques. Le résultat de la requête peut contenir plusieurs lignes et plus de deux colonnes.

  Si vous souhaitez effectuer l'agrégation basée sur le temps dans le cadre de votre requête, procédez comme suit :

  • Configurez votre requête pour agréger les données sur un intervalle de temps, pour trier les résultats par horodatages décroissants et pour limiter le nombre de lignes dans les résultats. Vous pouvez utiliser la clause LIMIT ou le sélecteur de période pour limiter le nombre de lignes dans le résultat de la requête.

    Par exemple, la requête suivante interroge une vue de journaux, puis agrège les données par heure, applique une limite et trie les résultats :

    SELECT TIMESTAMP_TRUNC(timestamp, HOUR) AS hour, severity, COUNT(*) AS count
    FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
    WHERE severity IS NOT NULL AND severity = "DEFAULT"
    GROUP BY hour,severity
    ORDER BY hour DESC
    LIMIT 10

    Voici la signification des champs de l'expression précédente :

    • PROJECT_ID : identifiant du projet.
    • LOCATION : emplacement de la vue de journaux ou de la vue d'analyse.
    • BUCKET_ID : nom ou ID du bucket de journaux.
    • LOG_VIEW_ID : identifiant de la vue de journaux, limité à 100 caractères et ne pouvant inclure que des lettres, des chiffres, des traits de soulignement et des traits d'union.

  • Définissez la dimension pour qu'elle corresponde à la colonne qui indique l'unité de temps. Par exemple, si votre requête agrège les données par heure et crée une colonne nommée hour, définissez le menu Dimension sur hour.

  • Sélectionnez Disable interval (Désactiver l'intervalle), car votre requête spécifie déjà l'intervalle d'agrégation. Dans l'exemple, cet intervalle est d'une heure.

  • Définissez la mesure sur la colonne numérique et définissez la fonction sur none (aucune).

    Remarque : Si votre requête effectue une agrégation basée sur le temps, assurez-vous de suivre les instructions précédentes. D'autres paramètres entraînent l'exécution d'opérations d'agrégation par votre requête et par Observability Analytics, ce qui fait que la jauge ou le tableau de données affiche des valeurs inattendues.

  Si vous souhaitez que l'agrégation basée sur le temps soit effectuée par Observability Analytics, procédez comme suit :

  • Configurez le sélecteur de période, qui affecte le nombre de lignes dans le résultat de la requête.
  • Définissez la dimension pour qu'elle corresponde à la colonne qui indique l'unité de temps. Par exemple, vous pouvez définir ce menu sur timestamp.
  • Définissez le menu Interval (Intervalle) sur un intervalle d'agrégation spécifique. Par exemple, définissez la valeur de ce champ sur 1 hour (1 heure). Ne sélectionnez pas Automatic interval (Intervalle automatique).
  • Définissez la mesure sur la colonne numérique et sélectionnez une fonction telle que sum (somme).

Modifier la dimension et la mesure

Vous pouvez choisir les lignes et les colonnes à représenter graphiquement en sélectionnant les champs de dimension et de mesure.

Remarque : Si les résultats de votre requête contiennent une colonne comportant de longues chaînes, telles que des messages d'erreur, et que vous sélectionnez cette colonne comme dimension ou répartition, votre graphique peut comporter des erreurs ou des valeurs inattendues.

• Dimension

  La dimension doit être une colonne d'horodatage, numérique ou de chaîne. Par défaut, la dimension est définie sur la première colonne basée sur l'horodatage du schéma. Si aucun horodatage n'est présent dans la requête, la première colonne de chaîne est sélectionnée comme dimension. Vous pouvez également personnaliser la dimension dans le panneau Chart display (Affichage du graphique). Lorsqu'une colonne d'horodatage est sélectionnée comme dimension, le graphique montre l'évolution des données au fil du temps. Lorsqu'une colonne de chaîne est sélectionnée comme dimension pour un graphique à barres, vous pouvez trier les données par ordre croissant ou décroissant, ce qui trie la dimension par ordre lexical. Vous pouvez également conserver l'ordre de tri `default`, qui trie la dimension en fonction des valeurs de la mesure correspondante par ordre décroissant.

  Par défaut, l'intervalle des horodatages est défini automatiquement, mais vous pouvez également sélectionner un intervalle personnalisé. Les intervalles automatiques modifient les valeurs en fonction du sélecteur de période pour conserver des groupes de taille similaire.

  Vous pouvez également désactiver l'intervalle, ce qui vous permet de spécifier vos propres agrégations et périodes dans la requête pour une analyse plus complexe. La désactivation de l'intervalle définit la fonction d'agrégation des mesures sur none. Seules les mesures numériques sont autorisées lorsque l'intervalle de dimension est désactivé.

  Remarque : Seule la colonne TIMESTAMP peut être utilisée comme dimension d'horodatage. Pour utiliser DATE et DATETIME, vous devez utiliser la CAST() fonction pour convertir les types de données en TIMESTAMP.

• Mesure

  Vous pouvez sélectionner plusieurs mesures dans le panneau Chart display (Affichage du graphique). Lorsque vous sélectionnez une mesure, vous devez également sélectionner la fonction d'agrégation à effectuer sur ses valeurs groupées, telles que count, sum, average et percentile-99. Par exemple, count-distinct renvoie le nombre de valeurs uniques dans une colonne donnée.

  Si vous cochez la case Disable interval (Désactiver l'intervalle) pour la dimension, l'option de fonction d'agrégation none est disponible. Si la dimension est une valeur de chaîne, la case Disable interval (Désactiver l'intervalle) ne s'affiche pas. Toutefois, la définition des fonctions d'agrégation d'une mesure sur none désactive également l'intervalle.

Ajouter une répartition

Remarque : Si votre graphique contient plusieurs mesures, vous ne pouvez pas ajouter de répartition.

Pour diviser une seule série de données en plusieurs séries de données en fonction d'une autre colonne, ajoutez une répartition.

Lorsque vous sélectionnez une répartition, choisissez des colonnes contenant un petit nombre de libellés courts et significatifs, comme region_name. Ne sélectionnez pas de champs susceptibles de contenir un grand nombre de chaînes ou de longues chaînes, comme textPayload.

Par exemple, consultez la configuration de graphique suivante, où le champ Dimension est défini sur type, le champ Measure (Mesure) est défini sur Count rows (Nombre de lignes) et le champ Breakdown (Dimension au rapport) est défini sur severity (gravité) :

Dans la capture d'écran précédente, vous voyez une série de données empilées, où le type de ressource k8s_container est divisé en différents types de severity. Cela vous permet d'identifier le nombre de journaux de chaque type de gravité générés par une ressource donnée.

Enregistrer un graphique dans un tableau de bord personnalisé

Une fois qu'un graphique est généré à partir de votre requête, vous pouvez l'enregistrer dans un tableau de bord personnalisé. Les tableaux de bord personnalisés vous permettent d'afficher et d'organiser les informations qui vous sont utiles à l'aide de différents types de widgets. Ces tableaux de bord vous permettent également de définir des variables, qui sont des filtres au niveau du tableau de bord qui ne s'appliquent qu'à des widgets spécifiques. Pour appliquer une variable à un widget, vous devez modifier la requête. Pour en savoir plus, consultez Appliquer une variable à un widget.

Un tableau de bord affiche un message d'avertissement pour un widget contenant une requête SQL lorsque la requête s'exécute sur le moteur BigQuery et que les ressources interrogées ne se trouvent pas dans la même limite de propriété. Les limites de propriété sont déterminées par plusieurs facteurs, dont la hiérarchie des ressources utilisées par la requête. Pour éviter ces avertissements, configurez un périmètre de service.

Pour enregistrer votre graphique dans un tableau de bord, procédez comme suit :

1. Dans la Google Cloud console, accédez à la page Observability Analytics :

   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. Exécutez une requête pour générer un graphique, puis cliquez sur Save to dashboard (Enregistrer dans le tableau de bord).

3. Dans la boîte de dialogue Save to dashboard (Enregistrer dans le tableau de bord), saisissez un titre pour votre graphique et sélectionnez le tableau de bord dans lequel vous souhaitez l'enregistrer.

4. Facultatif : Pour afficher le tableau de bord personnalisé, dans la notification toast, cliquez sur View dashboard.

Pour afficher la liste des tableaux de bord personnalisés contenant des graphiques générés par des requêtes SQL, accédez au bouton Save to dashboard (Enregistrer dans le tableau de bord), puis cliquez sur Menu.

Modifier un graphique enregistré dans un tableau de bord personnalisé

Vous pouvez modifier un graphique après l'avoir enregistré dans un tableau de bord. Pour en savoir plus, consultez Modifier la configuration d'un widget. Dans la boîte de dialogue Configure widget (Configurer le widget), vous pouvez effectuer les opérations suivantes :

• Modifier les données que vous interrogez.
• Modifier la requête utilisée pour générer un graphique.
• Personnaliser la configuration du graphique pour visualiser différentes données.

Limites

• Si votre Google Cloud projet se trouve dans un dossier qui utilise Assured Workloads, les graphiques que vous générez ne peuvent pas être affichés dans un tableau de bord personnalisé.

• Les filtres au niveau du tableau de bord ne s'appliquent pas aux graphiques générés à partir d'une requête SQL.

• Les colonnes sélectionnées doivent comporter au moins une ligne avec une valeur non nulle.

• Si vous enregistrez une requête et personnalisez la configuration du graphique, la configuration personnalisée n'est pas enregistrée.

• Si votre requête contient déjà des agrégations, le graphique généré peut être différent en raison de l'agrégation supplémentaire qui est automatiquement appliquée par Observability Analytics.

• Les chemins JSON doivent être convertis en chaînes ou en nombres pour être représentés graphiquement.

Exemples de requêtes

Cette section fournit des exemples de requêtes SQL pour représenter graphiquement les résultats de vos requêtes. Pour obtenir des insights plus utiles à partir de vos journaux, personnalisez la configuration du graphique. Pour utiliser les exemples de requêtes, procédez comme suit :

1. Dans la Google Cloud console, accédez à la page Observability Analytics :

   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. Identifiez le nom de la table pour la vue de journaux que vous souhaitez interroger.

   Pour identifier ce nom, accédez à la liste Log views (Vues de journaux), recherchez la vue de journaux, puis sélectionnez Query (Requête). Le volet Query (Requête) est rempli avec une requête par défaut, qui inclut le nom de la table de la vue de journaux interrogée. Le nom de la table est au format project_ID.region.bucket_ID.view_ID.

   Pour en savoir plus sur l'accès à la requête par défaut, consultez Interroger une vue de journaux.

3. Remplacez VIEW par le nom de la table de la vue de journaux que vous souhaitez interroger, puis copiez la requête.

4. Collez la requête dans le volet Query (Requête), puis cliquez sur Run query (Exécuter la requête).

Représenter graphiquement les entrées de journal par emplacement et par gravité

La requête suivante sélectionne location et severity, avec l'emplacement converti en chaîne :

SELECT
  CAST(JSON_VALUE(resource.labels.location) AS STRING) AS location,
  severity,
FROM
  `VIEW`
WHERE resource.labels.location IS NOT NULL

Voici un exemple de graphique et de configuration de graphique :

Dans la capture d'écran précédente, la configuration du graphique est la suivante :

• Chart type (Type de graphique) : graphique à barres, horizontal
• Dimension: location, avec une limite de 10
• Measure (Mesure) : nombre de lignes
• Répartition : severity, avec une limite de cinq

Représenter graphiquement les journaux d'audit des accès aux données par BigQuery

La requête suivante filtre les journaux d'audit data_access BigQuery et sélectionne certains champs, tels que user_email, ip, auth_permission et job_execution_project. Par exemple, vous pouvez créer un graphique qui visualise la fréquence d'utilisation de l'API BigQuery par chaque principal au fil du temps.

SELECT
  timestamp,
  proto_payload.audit_log.authentication_info.principal_email as user_email,
  proto_payload.audit_log.request_metadata.caller_ip as ip,
  auth.permission as auth_permission,
  auth.granted as auth_granted,
  JSON_VALUE(data_access.resource.labels.project_id) AS job_execution_project,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(1)] AS referenced_project,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(3)] AS referenced_dataset,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(5)] AS referenced_table
FROM `VIEW` as data_access,
  UNNEST(proto_payload.audit_log.authorization_info) AS auth
WHERE
  log_id="cloudaudit.googleapis.com/data_access"
  AND data_access.resource.type = 'bigquery_dataset'

Voici un exemple de graphique et de configuration de graphique :

Dans la capture d'écran précédente, la configuration du graphique est la suivante :

• Chart type (Type de graphique) : graphique à barres, vertical
• Dimension: user_email, avec une limite de cinq
• Measure (Mesure) : nombre de lignes
• Répartition : auth_permission, avec une limite de cinq

Étape suivante

• Pour obtenir une présentation d'Observability Analytics, consultez Présentation de l'interrogation et de l'analyse des journaux.

• Pour obtenir des exemples de requêtes, consultez Exemples de requêtes SQL.

• Pour découvrir comment effectuer des analyses avec des journaux d'audit à l'aide d' Observability Analytics, consultez Requêtes SQL pour les insights de sécurité.