Interroger un ensemble de données BigQuery associé

Ce document explique comment créer un ensemble de données associé pour un bucket de journaux, et comment interroger et afficher les journaux dans cet ensemble de données. Par exemple, vous pouvez créer un ensemble de données associé pour pouvoir exécuter des requêtes sur l'analyse de journaux à l'aide de vos emplacements BigQuery réservés. De même, vous pouvez avoir besoin d'un ensemble de données associé pour pouvoir écrire des requêtes dans BigQuery ou Looker Studio qui joignent vos données de journaux à d'autres données d'entreprise.

Vous ne pouvez pas créer d'ensemble de données associé à BigQuery pour une vue Analytics.

Si vous ne connaissez pas l'analyse de journaux, consultez la présentation de l'analyse de journaux.

Quand avez-vous besoin d'un ensemble de données associé ?

Vous n'avez pas besoin d'un ensemble de données BigQuery associé pour envoyer des requêtes à une vue de journaux sur la page Analyse de journaux lorsque vous utilisez le service Cloud Logging par défaut. Vous pouvez enregistrer et partager vos requêtes, et enregistrer les résultats dans un tableau de bord personnalisé.

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

Un ensemble de données BigQuery associé à un bucket de journaux permet à BigQuery de lire les données du bucket de journaux.

Si vous exécutez vos requêtes sur des emplacements BigQuery réservés, elles sont soumises à la tarification par capacité de calcul. De plus, si vous interrogez vos données à l'aide d'un service autre que Log Analytics, vos requêtes peuvent être soumises à d'autres frais en fonction de ce service. Consultez la page des tarifs du service que vous utilisez.

Correspondance entre les buckets et les vues de journaux et les objets BigQuery

Lorsque vous créez un ensemble de données BigQuery associé pour un bucket de journaux, un nouvel ensemble de données devient disponible dans BigQuery. Vous spécifiez le nom de l'ensemble de données associé lors du processus d'association. Toutes les vues de journaux du bucket de journaux sont automatiquement mappées aux vues virtuelles de l'ensemble de données. Le nom d'une vue virtuelle est identique à celui de la vue de journal correspondante.

Par exemple, supposons que le projet my_project comporte un bucket de journaux nommé example et que ce bucket de journaux comporte une vue de journaux nommée _AllLogs. Si vous créez un ensemble de données associé pour ce bucket de journaux avec le nom my_dataset, la page Explorateur de BigQuery affiche une entrée my_project. Un enfant de l'entrée my_project est un ensemble de données nommé my_dataset, et cet ensemble de données liste une vue virtuelle nommée _AllLogs.

Implications du contrôle d'accès lorsque vous utilisez des ensembles de données associés

Lorsqu'un principal interroge une vue sur un ensemble de données BigQuery associé, cette requête s'exécute via le niveau d'autorisation BigQuery, et non via le niveau d'autorisation Cloud Logging. Par conséquent, les rôles et autorisations BigQuery accordés au compte principal sur l'ensemble de données associé déterminent s'il peut interroger l'ensemble de données.

Vous ne pouvez pas limiter un principal à une vue virtuelle spécifique dans un ensemble de données associé. Lorsqu'un principal a obtenu l'accès à l'ensemble de données associé, il peut interroger chaque vue de cet ensemble de données.

Avant de commencer

Cette section décrit les étapes à suivre avant de pouvoir utiliser Log Analytics.

Configurer des buckets de journaux

Assurez-vous que vos buckets de journaux ont été mis à niveau pour utiliser l'Analyse de journaux :

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

    Accéder à la page 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 colonne Log Analytics disponible affiche Ouvrir. Si l'option Mettre à niveau s'affiche, cliquez dessus et remplissez la boîte de dialogue.

Configurer les rôles et autorisations IAM

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

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

    Vous pouvez limiter une entité principale à 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 journal.

    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 les vues sur les 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 créer et interroger des ensembles de données associés, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet qui stocke le bucket de journaux :

    • Pour créer et afficher des ensembles de données associés : Rédacteur de configuration des journaux (roles/logging.configWriter)
    • Pour exécuter des requêtes sur des ensembles de données associés à l'aide d'emplacements BigQuery réservés :
    • Pour afficher les ensembles de données associés dans BigQuery Studio, accordez tous les rôles mentionnés dans cette étape, ainsi que le rôle suivant. Vous pouvez attribuer ce rôle à un ensemble de données ou à votre projet : Lecteur de données BigQuery (roles/bigquery.dataViewer)

Vérifier votre édition BigQuery

Si vous souhaitez interroger vos données de journaux depuis la page Log Analytics à l'aide d'emplacements BigQuery réservés et si vous utilisez des projets avec des contrôles de service de cloud privé virtuel (VPC), assurez-vous d'utiliser l'édition Enterprise de BigQuery. Pour en savoir plus, consultez Comprendre les éditions BigQuery.

Si vous souhaitez utiliser les fonctionnalités de BigQuery pour analyser vos données de journaux, mettez à niveau un bucket de journaux pour utiliser l'Analyse de journaux, puis créez un ensemble de données associé. Avec cette configuration, Logging stocke vos données de journaux, mais BigQuery peut les lire.

Console Google Cloud

Pour créer un lien vers un ensemble de données BigQuery pour un bucket de journaux existant, procédez comme suit :

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

    Accéder à la page 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. Localisez le bucket de journaux et vérifiez que la colonne Log Analytics disponible affiche Ouvrir.

    Si la colonne affiche Mettre à niveau, cela signifie que le bucket de journaux n'a pas été mis à niveau pour utiliser l'Analyse de journaux. Configurer l'analyse de journaux :

    1. Cliquez sur Mettre à jour.
    2. Cliquez sur Confirmer dans la boîte de dialogue.

    Une fois la mise à niveau terminée, passez à l'étape suivante.

  3. Sur le bucket de journaux, cliquez sur Plus, puis sur Modifier le bucket.

    La boîte de dialogue Modifier le bucket de journaux s'ouvre.

  4. Sélectionnez Créer un ensemble de données BigQuery associé à ce bucket, puis saisissez le nom du nouvel ensemble de données.

    Le nom de l'ensemble de données doit être unique pour chaque Google Cloud projet. Si vous saisissez le nom d'un ensemble de données existant, l'erreur suivante s'affiche : Dataset name must be unique in the selected region.

  5. Cliquez sur OK, puis sur Mettre à jour le bucket.

    Une fois que Logging affiche le nom de l'ensemble de données associé sur la page Stockage des journaux, BigQuery peut mettre plusieurs minutes à reconnaître l'ensemble de données.

gcloud

Pour créer un ensemble de données associé pour un bucket de journaux mis à niveau pour utiliser l'Analyse de journaux, exécutez la commande gcloud logging links create :

gcloud logging links create LINK_ID --bucket=BUCKET_ID --location=LOCATION

Le LINK_ID que vous fournissez est utilisé comme nom de l'ensemble de données BigQuery. La valeur de ce champ doit être unique pour votre projet Google Cloud .

La commande links create est asynchrone. Le retour d'une méthode asynchrone est un objet Operation, qui contient des informations sur la progression de la méthode. Une fois la méthode terminée, l'objet Operation contient l'état. Pour en savoir plus, consultez Méthodes d'API asynchrones.

L'exécution de la commande links create prend plusieurs minutes.

Par exemple, la commande suivante crée un ensemble de données associé nommé mylink pour le bucket de journaux nommé my-bucket :

gcloud logging links create mylink --bucket=my-bucket --location=global

Le nom de l'ensemble de données doit être unique pour chaque Google Cloud projet. Si vous essayez de créer un ensemble de données portant le même nom qu'un ensemble de données existant, l'erreur suivante s'affiche :

BigQuery dataset with name "LINK_ID" already exists.

Si vous tentez de créer un ensemble de données associé pour un bucket de journaux qui n'a pas été mis à niveau pour utiliser l'Analyse de journaux, l'erreur suivante s'affiche :

A link can only be created for an analytics-enabled bucket.

REST

Pour créer un ensemble de données BigQuery associé à un bucket de journaux existant qui a été mis à niveau pour utiliser l'analyse de journaux, appelez la méthode asynchrone projects.locations.buckets.links.create de l'API Cloud Logging.

Préparez les arguments de la méthode comme suit :

  1. Créez le corps de la requête pour la commande create. Le corps de la requête est mis en forme en tant qu'objet Link.
  2. Pour le paramètre de requête de la commande, utilisez linkId=LINK_ID. Le LINK_ID que vous fournissez est utilisé comme nom de l'ensemble de données BigQuery. La valeur de ce champ doit être unique pour votre projet Google Cloud .

La réponse aux méthodes asynchrones est un objet Operation. Cet objet contient des informations sur la progression de la méthode. Une fois la méthode terminée, l'objet Operation contient l'état. Pour en savoir plus, consultez Méthodes d'API asynchrones.

L'exécution de la méthode links.create prend plusieurs minutes.

Le nom de l'ensemble de données doit être unique pour chaque Google Cloud projet. Si vous essayez de créer un ensemble de données portant le même nom qu'un ensemble de données existant, l'erreur suivante s'affiche :

BigQuery dataset with name "LINK_ID" already exists.

Si vous tentez de créer un ensemble de données associé pour un bucket de journaux qui n'a pas été mis à niveau pour utiliser l'Analyse de journaux, l'erreur suivante s'affiche :

A link can only be created for an analytics-enabled bucket.

Exécuter des requêtes depuis BigQuery

Lorsque vous disposez d'un bucket de journaux qui utilise l'analyse de journaux et des ensembles de données associés, vous pouvez afficher et interroger vos ensembles de données associés à l'aide de la page BigQuery Studio. Cette configuration vous permet d'analyser vos ensembles de données à l'aide de commandes, de workflows et d'ensembles de données disponibles uniquement dans BigQuery Studio.

Pour ouvrir BigQuery à partir de l'Analyse de journaux, puis interroger l'ensemble de données associé, procédez comme suit :

  1. Assurez-vous qu'un ensemble de données associé existe pour le bucket de journaux qui héberge la vue des journaux que vous souhaitez interroger :

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

      Accéder à la page 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. Localisez le bucket de journaux et vérifiez que la colonne Ensemble de données associé à BigQuery affiche une URL. Si l'entrée est vide, vous devez créer un ensemble de données associé. Pour en savoir plus sur ces étapes, consultez Créer un ensemble de données associé à BigQuery.

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

  3. Dans la liste Vues du journal, recherchez et sélectionnez la vue du journal.

  4. Dans le volet Schéma, sélectionnez Requête.

    Le volet Requête est renseigné avec une requête par défaut. Vous pouvez également saisir une requête dans le volet Requête ou modifier une requête affichée.

  5. Dans la barre d'outils, développez le bouton Exécuter la requête ou Exécuter sur BigQuery, puis sélectionnez Ouvrir dans BigQuery.

    La page BigQuery Studio s'ouvre. L'instruction FROM de la requête est modifiée pour spécifier le chemin d'accès à la vue des journaux dans l'ensemble de données associé à l'aide de la syntaxe du chemin d'accès aux tables BigQuery.

    Vous pouvez également modifier la requête affichée.

  6. Sur la page BigQuery Studio, cliquez sur Exécuter la requête.

Exécuter des requêtes d'analyse de journaux sur vos emplacements BigQuery réservés

Si vous souhaitez réduire au minimum le temps d'exécution de vos requêtes d'analyse de journaux, exécutez-les sur vos emplacements BigQuery réservés. La page Analyse de journaux est préconfigurée pour utiliser le service d'analyse de journaux par défaut. Cela signifie que vos requêtes doivent rivaliser avec d'autres requêtes pour un espace de slot limité. Lorsque aucun emplacement n'est disponible, l'exécution de votre requête est retardée. Vous pouvez éliminer ces délais en exécutant vos requêtes sur des emplacements BigQuery réservés.

Pour exécuter une requête SQL sur une vue de journaux :

  1. Assurez-vous qu'un ensemble de données associé existe pour le bucket de journaux qui héberge la vue des journaux que vous souhaitez interroger :

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

      Accéder à la page 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. Localisez le bucket de journaux et vérifiez que la colonne Ensemble de données associé à BigQuery affiche une URL. Si l'entrée est vide, vous devez créer un ensemble de données associé. Pour en savoir plus sur ces étapes, consultez Créer un ensemble de données associé à BigQuery.

  2. Assurez-vous d'avoir configuré vos emplacements BigQuery réservés :

    1. Créer une réservation avec des emplacements dédiés
    2. Créer des attributions de réservation

  3. Configurez l'analyse de journaux pour exécuter vos requêtes sur vos emplacements BigQuery réservés :

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

    2. Dans la liste Vues des journaux, recherchez la vue, puis sélectionnez Requête ou saisissez une requête.

      Si le volet de requête affiche un message d'erreur faisant référence à l'instruction FROM, cela signifie que la table ne peut pas être résolue en une vue de journaux spécifique. Pour savoir comment résoudre cet échec, consultez Erreur FROM clause must contain exactly one log view.

    3. Accédez à la barre d'outils et assurez-vous qu'un bouton intitulé Exécuter sur BigQuery s'affiche.

      Si la barre d'outils affiche Exécuter la requête, cliquez sur Paramètres, puis sélectionnez BigQuery.

      Si le bouton Exécuter sur BigQuery est désactivé, vous devez créer un ensemble de données associé.

    4. Exécutez votre requête.

      Vous pouvez utiliser les options de la barre d'outils pour mettre en forme votre requête, l'effacer et ouvrir la documentation de référence sur le SQL BigQuery.

Étapes suivantes