Façonnez l'avenir des opérations logicielles et faites entendre votre voix en répondant à l'enquête sur l'état du DevOps en 2021.

Schéma BigQuery des journaux

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

Présentation

Vous pouvez acheminer des 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 pour vous 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 certains champs de charge utile structurée.

Les récepteurs de journaux diffusent les données de journalisation en flux continu 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.

Conventions de dénomination de champs

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

  • Les noms de champ d'entrée de journal ne peuvent pas comporter plus de 128 caractères.

  • Les noms de champ d'entrée de journal ne peuvent être composés que de caractères alphanumériques. Tous les caractères non compatibles 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 des champs des entrées de journal doivent commencer par un caractère alphanumérique, même après la transformation. tous les traits de soulignement principaux 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ée de journal fournis par l'utilisateur, les noms des champs BigQuery correspondants sont normalisés en minuscules, mais la dénomination est préservée.

  • Pour les champs des charges utiles structurées, tant que le spécificateur @type n'apparaît pas, les noms de champ BigQuery correspondants sont normalisés en minuscules, mais la dénomination est préservé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 décrit les noms de champs spéciaux des schémas BigQuery pour les entrées de journal qui possèdent des charges utiles contenant le spécificateur @type. Cela inclut les entrées du journal d'audit routées vers BigQuery.

Les charges utiles des entrées de journal peuvent contenir des données structurées. Tous les champs structurés peuvent inclure un spécificateur de type facultatif au format suivant:

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

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

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. sont ignorés. Lors du traitement des champs de charge utile structurée de 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

Quelques exceptions s'appliquent aux règles précédentes pour les champs contenant des indicateurs 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 schémas 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 lors de la réception de 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 BigQuery standards, car les règles de spécification de type ne s'appliquent pas aux champs imbriqués.

Par conséquent, 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 dans les journaux d'audit exportés

Si vous ne travaillez pas avec des 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 acheminé depuis 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 acheminée vers BigQuery, comment le champ tableInsertRequest serait-il référencé ? Avant le nom 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 fournit une présentation des tables partitionnées pour les journaux routé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 journaux. Logging utilise deux types de tables pour organiser les données qu'il achemine: 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. Toutefois, il existe deux différences principales entre les types de table:

  • Performances: en divisant une grande table en partitions plus petites, vous pouvez améliorer les performances des requêtes et maîtriser 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 Exporter des entrées de journal à l'aide de l'explorateur de journaux.

Pour obtenir des instructions sur l'utilisation du SDK Cloud ou de l'interface de ligne de commande, 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. L'entrée de journal génère une table dont les colonnes sont basées sur les champs de l'entrée de journal et sur leur type. Si de nouveaux champs apparaissent dans les entrées suivantes, le schéma de la table est mis à jour pour inclure les nouvelles colonnes. Toutefois, si le type de champ change pour un champ existant, les entrées de journal les plus récentes qui ne correspondent pas au schéma sont ignorées.

Par exemple, si le champ jsonPayload.user_id de l'entrée de journal initiale est string, cette entrée de journal génère une table dans laquelle ce champ est de type string (chaîne). Si vous lancez ensuite la journalisation jsonPayload.user_id en tant que array, ces entrées de journal ne sont pas insérées dans la table et sont perdues.

Logging communique cette perte de données au projet Cloud contenant le récepteur de routage de la façon 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 le problème des entrées de journal suivantes et éviter d'autres pertes de données, 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 section Mettre à jour des récepteurs.

Afficher les journaux

Vous pouvez afficher vos journaux et leur schéma BigQuery en sélectionnant une table dans l'interface utilisateur Web de BigQuery qui a reçu des entrées de journal de Cloud Logging.