Afficher les journaux acheminés vers BigQuery

Ce document explique comment trouver les entrées de journal que vous avez acheminées de Cloud Logging vers des tables BigQuery. Les récepteurs Logging diffusent en streaming les données de journalisation dans BigQuery par petits lots, ce qui vous permet d'interroger les données sans exécuter de tâche de chargement. Pour vous aider à créer des requêtes et à comprendre le format de votre table BigQuery, ce document décrit également le schéma BigQuery pour les journaux acheminés.

Cloud Logging utilise l'ancienne API de streaming pour diffuser vos entrées de journal dans BigQuery. En règle générale, les entrées de journal sont visibles dans BigQuery dans la minute qui suit. Toutefois, lorsqu'une table est créée, les premières entrées de journal peuvent mettre plusieurs minutes à être disponibles.

Avant de commencer

Pour en savoir plus sur les récepteurs, consultez la page Présentation des modèles de routage et de stockage: récepteurs.

Pour savoir comment acheminer vos journaux, consultez la section Acheminer les journaux vers des destinations compatibles.

Pour découvrir comment les champs des entrée de journal acheminées sont nommés, consultez la section Schéma BigQuery des journaux acheminés.

Voir les journaux

Pour afficher les journaux acheminés vers BigQuery, procédez comme suit:

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery Studio

   Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

2. Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.

   Les entrées de journal sont visibles dans l'onglet Détails. Vous pouvez également interroger la table pour qu'elle renvoie vos données.

Exemples de requêtes

Pour en savoir plus sur la syntaxe des requêtes BigQuery, consultez la documentation de référence sur les requêtes. Les fonctions de caractères génériques de table sont particulièrement utiles, car elles vous permettent d'interroger plusieurs tables. L'opérateur FLATTEN est également très pratique, car il vous permet d'afficher des données à partir de champs répétés.

Exemple de requête Compute Engine

La requête BigQuery suivante récupère les entrées de journal de plusieurs jours et de différents types de journaux :

• La requête recherche les trois derniers jours des journaux syslog et apache-access. Elle a été exécutée le 23 février 2020 et couvre toutes les entrées de journal reçues les 21 et 22 février, ainsi que les entrées reçues le 23 février jusqu'à la création de la requête.

• La requête récupère les résultats d'une seule instance de Compute Engine : 1554300700000000000.

SELECT
  timestamp AS Time,
  logName as Log,
  textPayload AS Message
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.syslog_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())),
  (TABLE_DATE_RANGE(my_bq_dataset.apache_access_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP()))
WHERE
  resource.type == 'gce_instance'
  AND resource.labels.instance_id == '1554300700000000000'
ORDER BY time;

Voici quelques exemples de lignes de sortie :

Row | Time                    | Log                                         | Message
--- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------
 5  | 2020-02-21 03:40:14 UTC | projects/project-id/logs/syslog             | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269;
 6  | 2020-02-21 04:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 7  | 2020-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2020:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2020-02-21 05:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 9  | 2020-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2020:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

Exemple de requête App Engine

La requête BigQuery suivante récupère les requêtes App Engine du mois dernier qui n'ont pas abouti :

SELECT
  timestamp AS Time,
  protoPayload.host AS Host,
  protoPayload.status AS Status,
  protoPayload.resource AS Path
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_,
    DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP()))
WHERE
  protoPayload.status != 200
ORDER BY time

Voici une partie des résultats :

Row | Time                    | Host                                  | Status | Path
--- | ----------------------- | ------------------------------------- | ------ | ------
 6  | 2020-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2020-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2020-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2020-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

Schéma BigQuery des journaux routés

Les schémas de table BigQuery pour les journaux acheminés se basent sur la structure du type LogEntry et sur le contenu des charges utiles des journaux. Cloud Logging applique également des règles pour raccourcir les noms de champs des schémas BigQuery pour les journaux d'audit et pour certains champs de charge utile structurée. Vous pouvez afficher le schéma d'une table en sélectionnant une comportant des entrées de journal acheminées dans l'interface BigQuery.

Conventions de dénomination de champs

Des conventions de dénomination s'appliquent aux champs d'entrées de journal lors de l'envoi de journaux à BigQuery :

• Les noms de champs d'entrées de journal ne peuvent pas dépasser 128 caractères.

• Les noms de champs d'entrées de journal ne peuvent contenir que des caractères alphanumériques. Tous les caractères non acceptés sont supprimés des noms de champs et remplacés par des traits de soulignement. Par exemple, jsonPayload.foo%% serait transformé en jsonPayload.foo__.

  Les noms de champs d'entrées de journal doivent commencer par un caractère alphanumérique, même après la transformation. Tous les traits de soulignement au début sont supprimés.

• Pour les champs d'entrée de journal appartenant au type LogEntry, les noms des champs BigQuery correspondants sont identiques aux noms des champs des entrée de journal.

• Pour les champs d'entrées de journal fournis par l'utilisateur, les noms de champs BigQuery correspondants sont normalisés en minuscules, mais la dénomination est conservée.

• Pour les champs de charges utiles structurées, tant que le spécificateur @type n'apparaît pas, les noms de champs BigQuery correspondants sont normalisés en minuscules, mais la dénomination est conservée.

  Pour en savoir plus sur les charges utiles structurées contenant le spécificateur @type, consultez la section Champs de charge utile avec @type sur cette page.

Les exemples suivants montrent comment s'appliquent ces conventions de dénomination :

Champs de charge utile avec @type

Cette section traite des noms de champs spéciaux des schémas BigQuery pour les entrées de journal dont les charges utiles contiennent le spécificateur @type. Cela inclut les entrées de journal d'audit acheminées vers BigQuery.

Les charges utiles des entrées de journal peuvent contenir des données structurées. Tout champ structuré peut inclure un spécificateur de type facultatif au format suivant :

@type: type.googleapis.com/[TYPE]

Les règles de dénomination expliquent pourquoi un champ protoPayload d'une entrée de journal d'audit peut être mappé au champ de schéma BigQuery protopayload_auditlog.

Règles de dénomination pour @type

Les champs structurés qui possèdent des spécificateurs de type reçoivent généralement des noms de champs BigQuery suivis d'un [TYPE]. La valeur de [TYPE] peut être n'importe quelle chaîne.

Les règles de dénomination de @type ne s'appliquent qu'au niveau supérieur de jsonPayload ou protoPayload. Les champs imbriqués sont ignorés. Lorsque vous traitez des champs de charge utile structurée au niveau supérieur, Logging supprime le préfixe type.googleapis.com.

Par exemple, le tableau suivant présente le mappage des champs de charge utile structurée de niveau supérieur avec les noms de champs BigQuery :

Certaines exceptions s'appliquent aux règles précédentes pour les champs contenant des spécificateurs de type :

• Dans les journaux de requêtes App Engine, le nom de la charge utile des journaux acheminés vers BigQuery est protoPayload, même si elle possède un spécificateur de type.

• Cloud Logging applique des règles spéciales pour raccourcir les noms de champs des schémas BigQuery pour les journaux d'audit. Ce point est abordé dans la section Champs des journaux d'audit de cette page.

Exemple

Cet exemple montre comment les champs de charge utile structurée sont nommés et utilisés lorsqu'ils sont reçus par BigQuery.

Imaginons que la charge utile d'une entrée de journal possède la structure suivante :

jsonPayload: {
  @type: "type.googleapis.com/google.cloud.v1.CustomType"
    name_a: {
      sub_a: "A value"
    }
    name_b: {
      sub_b: 22
    }
  }

Dans ce cas, le mappage avec les champs BigQuery est tel que décrit ci-dessous :

• Le champ structuré de niveau supérieur jsonPayload contient un spécificateur @type. Son nom BigQuery est jsonpayload_v1_customtype.

• Les champs imbriqués sont traités avec les règles de dénomination standards de BigQuery, car les règles de spécificateur de type ne s'appliquent pas aux champs imbriqués.

Ainsi, les noms BigQuery suivants sont définis pour la charge utile de l'entrée de journal :

  jsonpayload_v1_customtype
  jsonpayload_v1_customtype._type
  jsonpayload_v1_customtype.name_b
  jsonpayload_v1_customtype.name_b.sub_b
  jsonpayload_v1_customtype.name_a
  jsonpayload_v1_customtype.name_a.sub_a

Champs de journaux d'audit

Si vous n'utilisez pas les journaux d'audit acheminés vers BigQuery, vous pouvez ignorer cette section.

Les champs de charge utile de journal d'audit protoPayload.request, protoPayload.response et protoPayload.metadata contiennent des spécificateurs @type, mais sont traités comme des données JSON. Autrement dit, leurs noms de schéma BigQuery correspondent à leurs noms de champ suivis de Json, et ils contiennent des données de chaîne au format JSON.

Les deux ensembles de noms de champs de charge utile de journal d'audit sont répertoriés dans le tableau suivant :

Notez que la convention de dénomination serviceData est spécifique aux journaux d'audit qui sont générés par BigQuery, puis exportés de Cloud Logging vers BigQuery. Ces entrées du journal d'audit contiennent un champ serviceData contenant le spécificateur @type type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Exemple

Une entrée de journal d'audit générée par BigQuery contient un champ dont le nom est le suivant :

protoPayload.serviceData.tableInsertRequest

Si cette entrée de journal était ensuite exportée vers BigQuery, comment le champ tableInsertRequest serait-il référencé ? Avant d'être raccourci, le nom de champ correspondant dans BigQuery serait le suivant :

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Après avoir été raccourci, le même champ est référencé dans les tables BigQuery de la manière suivante :

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Organisation des tables

Cette section présente les tables partitionnées pour les journaux acheminés vers BigQuery.

Lorsque vous acheminez des journaux vers un ensemble de données BigQuery, Logging crée des tables pour conserver les entrées de journal. La première entrée de journal reçue par BigQuery détermine le schéma de la table BigQuery de destination. BigQuery crée une table dont les colonnes sont basées sur les champs de la première entrée de journal et leur type. Les entrées de journal suivantes peuvent entraîner une incohérence de schéma. Pour en savoir plus sur les cas de non-concordance et leur gestion, consultez la section Incohérences dans le schéma.

Logging organise les données qu'il achemine au moyen de deux types de tables : les tables segmentées par date et les tables partitionnées. Les deux types de table segmentent les données des journaux en fonction des champs timestamp des entrées de journal. Cependant, il existe deux différences majeures entre les types de table :

• Performances : une table partitionnée divise une grande table en partitions plus petites. Vous pouvez ainsi améliorer les performances des requêtes et, par conséquent, mieux contrôler les coûts BigQuery en réduisant le nombre d'octets lus par une requête.

• Nomenclature des tables : les types de tables utilisent différentes conventions de dénomination, comme indiqué dans la section ci-dessous.

Organisation des tables

Les entrées de journal sont segmentées dans des tables BigQuery dont l'organisation et les noms sont basés sur le nom des entrées de journal et sur leur horodatage.

Les noms des tables sont associés à la date du calendrier de l'horodatage UTC de l'entrée de journal, au format de base ISO 8601 (AAAAMMJJ).

Le tableau suivant montre des exemples illustrant la façon dont les noms des journaux et les horodatages sont mappés au nom des tables dans BigQuery :

¹ Les horodatages d'entrée de journal utilisent l'heure UTC (temps universel coordonné).

Créer des tables partitionnées

Lorsque vous créez un récepteur pour acheminer vos journaux vers BigQuery, vous pouvez utiliser des tables segmentées par date ou des tables partitionnées. La sélection par défaut est une table segmentée par date:

Pour savoir comment créer des récepteurs, consultez les ressources suivantes:

• Console Google Cloud : Acheminer les journaux vers les destinations compatibles.

• Google Cloud CLI : gcloud logging sinks create.

Incohérences dans le schéma

La première entrée de journal reçue par BigQuery détermine le schéma de la table BigQuery de destination. BigQuery crée une table dont les colonnes sont basées sur les champs de la première entrée de journal et leur type.

Une erreur de correspondance de schéma se produit lorsque les entrées de journal sont écrites dans la table de destination et que l'une des erreurs suivantes se produit :

• Une entrée de journal ultérieure modifie le type de champ d'un champ existant de la table.

  Par exemple, si le champ jsonPayload.user_id de l'entrée de journal initiale est défini sur string, cette entrée de journal génère une table dans laquelle ce champ est de type chaîne. La journalisation ultérieure de jsonPayload.user_id en tant que array entraînera une incohérence de schéma.

• Une nouvelle entrée de journal contient un champ qui ne figure pas dans le schéma actuel. L'insertion de ce champ dans la table de destination dépasserait la limite de colonnes BigQuery.

  La table de destination peut accepter le nouveau champ s'il ne dépasse pas la limite de colonnes.

Lorsque BigQuery identifie une incohérence de schéma, il crée une table dans l'ensemble de données correspondant pour stocker les informations d'erreur. Le type d'une table détermine son nom. Pour les tables segmentées par date, le format des noms est export_errors_YYYYMMDD. Pour les tables partitionnées, le format des noms est export_errors. Pour en savoir plus, consultez la section Organisation des tables.

Lors de l'exportation des entrées de journal, Logging envoie des messages par lot à BigQuery. BigQuery utilise les règles suivantes pour déterminer la table dans laquelle les entrées de journal du lot de messages actuel sont écrites :

• Lorsqu'une modification de type de champ se produit, seules les entrées de journal ayant provoqué une non-concordance du schéma sont écrites dans la table d'erreur. Les entrées de journal du lot de messages actuel qui n'entraînent pas d'incohérence de schéma sont écrites dans la table de destination d'origine.

• Lorsque la limite de colonnes est dépassée, toutes les entrées de journal du lot de messages actuel sont écrites dans la table d'erreur.

Schéma de la table d'erreurs

La table d'erreurs contient des données provenant de LogEntry et des informations sur la non-concordance:

• logEntry: contient l'entrée de journal complète. Cependant, l'entrée de journal est convertie de JSON en chaîne.
• schemaErrorDetail: contient le message d'erreur complet renvoyé par BigQuery.
• sink: contient le chemin d'accès complet de la ressource pour le récepteur de journal.
• logName: extrait de LogEntry.
• timestamp: extrait de LogEntry.
• receiveTimestamp: extrait de LogEntry.
• severity: extrait de LogEntry.
• insertId: extrait de LogEntry.
• trace: extrait de LogEntry.
• resourceType: extrait de LogEntry.

Logging communique les incohérences de schéma au projet Google Cloud qui contient le récepteur de routage de la manière suivante:

• Les propriétaires du projet reçoivent un e-mail. Les détails incluent l'ID de projet Google Cloud, le nom du récepteur et la destination.
• La page "Activité" de la console Google Cloud affiche une erreur Stackdriver Config error. Les détails incluent le nom du récepteur et la destination, ainsi qu'un lien vers un exemple d'entrée de journal à l'origine de l'erreur.

Éviter les futurs cas de non-correspondance de type de champ

Pour corriger les incohérences de type de champ pour les entrées de journal ultérieures, corrigez le type de champ afin qu'il corresponde au schéma actuel. Pour savoir comment corriger un type de champ, consultez Modifier le type de données d'une colonne.

Il est parfois impossible de modifier le type de champ. Par exemple, vous ne pouvez pas modifier le type de champ pour les journaux générés automatiquement par les services Google Cloud. Pour éviter les incompatibilités de schéma lorsque vous ne pouvez pas modifier un type de champ, renommez la table ou modifiez les paramètres du récepteur, afin que Logging recrée la table dans un autre ensemble de données. Pour obtenir des instructions, consultez la page Gérer les récepteurs.

Dépannage

Si les journaux semblent manquants dans la destination de votre récepteur ou si vous pensez que votre récepteur n'achemine pas correctement les journaux, consultez la section Résoudre les problèmes de routage des journaux.

Tarifs

Cloud Logging ne facture pas l'acheminement des journaux vers une destination compatible. Toutefois, la destination peut appliquer des frais. À l'exception du bucket de journaux _Required, Cloud Logging facture le streaming de journaux dans des buckets de journaux et le stockage pendant une durée supérieure à la période de conservation par défaut du bucket de journaux.

Cloud Logging ne facture pas la copie des journaux, la définition des champs d'application des journaux ni les requêtes émises via les pages Explorateur de journaux ou Analyse de journaux.

Pour en savoir plus, consultez les documents suivants :

• Synthèse des tarifs Cloud Logging

• Coûts de destination:

  • Tarifs de Cloud Storage
  • Tarifs de BigQuery
  • Tarifs de Pub/Sub
  • Tarifs de Cloud Logging
• Les frais de génération de journaux de flux VPC s'appliquent lorsque vous envoyez vos journaux de flux de cloud privé virtuel (VPC) vers Cloud Logging, puis les excluez de ce service.