Schéma BigQuery des journaux

Cette page décrit la mise en forme et les règles applicables lors de l'acheminement des entrées de journal de Cloud Logging vers BigQuery.

Présentation

Vous pouvez acheminer les entrées de journal de Cloud Logging vers BigQuery à l'aide de récepteurs. Lorsque vous créez un récepteur, vous définissez un ensemble de données BigQuery comme destination. Logging envoie les entrées de journal correspondant aux règles du récepteur aux tables partitionnées créées dans cet ensemble de données BigQuery.

Les schémas de table BigQuery pour les données reçues de Cloud Logging sont basés sur la structure du type LogEntry et sur le contenu des charges utiles des entrées de journal. 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.

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 en savoir plus, consultez la section Insérer des données en streaming dans BigQuery. Pour en savoir plus sur les tarifs, consultez la section "Insertions en flux continu" de la page Tarifs de BigQuery : Tarifs de l'ingestion de données.

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ées de journaux appartenant au type LogEntry, les noms des champs BigQuery correspondants sont identiques aux noms des champs des entrées de journaux.

  • 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 :

Champ d'entrée de journal Mappage de type LogEntry Nom de champ BigQuery
insertId insertId insertId
textPayload textPayload textPayload
httpRequest.status httpRequest.status httpRequest.status
httpRequest.requestMethod.GET httpRequest.requestMethod.[ABC] httpRequest.requestMethod.get
resource.labels.moduleid resource.labels.[ABC] resource.labels.moduleid
jsonPayload.MESSAGE jsonPayload.[ABC] jsonPayload.message
jsonPayload.myField.mySubfield jsonPayload.[ABC].[XYZ] jsonPayload.myfield.mysubfield

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 :

Charge utile Indicateur @type de la charge utile Champ de charge utile Nom de champ BigQuery
jsonPayload (aucun) statusCode jsonPayload.statusCode
jsonPayload type.googleapis.com/abc.Xyz statusCode jsonpayload_abc_xyz.statuscode
protoPayload (aucun) statusCode protoPayload.statuscode
protoPayload type.googleapis.com/abc.Xyz statusCode protopayload_abc_xyz.statuscode

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 de 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 :

Champ d'entrée de journal Nom de champ BigQuery
protoPayload protopayload_auditlog
protopayload.metadata protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
Exemple : protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.responseJson

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

Tables partitionnées

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

Nom du journal Entrée de journal timestamp Nom de la table BigQuery
(segmentée par date)
Nom de la table BigQuery
(partitionnée)
syslog 2017-05-23T18:19:22.135Z syslog_20170523 syslog
apache-access 2017-01-01T00:00:00.000Z apache_access_20170101 apache_access
compute.googleapis.com/activity_log 2017-12-31T23:59:59.999Z compute_googleapis_com_activity_log_20171231 compute_googleapis_com_activity_log

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 obtenir des instructions sur l'utilisation de Google Cloud Console, consultez la page Configurer et gérer des récepteurs.

Pour obtenir des instructions sur l'utilisation de l'outil de ligne de commande gcloud, consultez la page 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.

  • De nouveaux champs sont ajoutés à une entrée de journal, ce qui entraîne le dépassement du nombre maximal de colonnes de la table de destination autorisé par BigQuery. Pour en savoir plus sur la limite du nombre de colonnes, consultez la page Quotas et limites de BigQuery.

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 de table détermine le nom de la table. Pour les tables segmentées par date, le format de dénomination est export_errors_YYYYMMDD. Pour les tables partitionnées, le format des noms est export_errors. Pour en savoir plus, consultez la page 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.

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

  • Champs LogEntry écrits dans la table d'erreur :

    • logName
    • timestamp
    • receiveTimestamp
    • severity
    • insertId
    • trace
    • resource.type
  • Informations sur les incohérences de schéma écrites dans la table d'erreur :

    • Chemin d'accès complet aux ressources pour le récepteur de journaux
    • Message d'erreur complet renvoyé par BigQuery
    • Entrée de journal complète. Cependant, l'entrée de journal est convertie de JSON en chaîne.

Logging communique les incohérences de schéma au projet 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 Google Cloud Console 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.
  • La métrique basée sur les journaux système exports/error_count vous informe du nombre total d'entrées de journal qui n'ont pas été acheminées en raison d'erreurs.

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. Vous pouvez également renommer la table ou modifier les paramètres du récepteur, afin que Stackdriver Logging recrée la table dans un autre ensemble de données. Pour obtenir des instructions, consultez la page Configurer et gérer des récepteurs.

Afficher les journaux

Pour obtenir des instructions sur l'affichage de vos journaux routés dans BigQuery, consultez la section Afficher les journaux dans les destinations de récepteur.