Schéma BigQuery des journaux exportés

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

Logging diffuse les données de journalisation vers BigQuery enregistrement par enregistrement, et non à l'aide de tâches de chargement. Cette approche permet d'interroger les données dans BigQuery sans attendre l'exécution d'une tâche de chargement. Pour en savoir plus, consultez la section Insérer des données en streaming dans BigQuery.

Les schémas de table BigQuery pour les journaux exporté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 spéciales pour raccourcir les noms de champs des schémas BigQuery pour les journaux d'audit. Vous pouvez afficher le schéma d'une table en sélectionnant une table qui comporte des entrées de journal exportées dans l'interface utilisateur Web de BigQuery.

Conventions de dénomination de champs

Des conventions de dénomination s'appliquent aux champs d'entrées de journal :

  • 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 fournis par l'utilisateur, la casse des lettres est normalisée 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, la casse de lettre est normalisée 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 page Champs de charge utile avec @type.

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

Le mappage des champs de charge utile structurée sur le nom des champs BigQuery est plus complexe lorsque le champ structuré contient un spécificateur @type. Ce point est abordé dans la section suivante.

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 des spécificateurs de type (champs @type). Cela inclut toutes les entrées de journal d'audit exportées qui sont conservées dans BigQuery. Cette section explique par exemple 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 des schémas

Les charges utiles des entrées de journal peuvent comprendre des données structurées, qui peuvent à leur tour contenir des champs structurés imbriqués. Tous les champs structurés peuvent inclure un indicateur de type facultatif au format suivant :

@type: type.googleapis.com/[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].

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

Si les charges utiles jsonPayload ou protoPayload contiennent d'autres champs structurés, ces champs internes sont mappés de la façon suivante :

  • Si le champ structuré imbriqué ne contient pas de spécificateur @type, son nom de champ BigQuery est identique au nom de champ d'origine, sauf qu'il est normalisé en lettres minuscules.
  • Si le champ structuré imbriqué contient un spécificateur @type, son nom de champ BigQuery est suivi d'un [TYPE] (réécrit). Ce nom est normalisé en lettres minuscules.

Il existe quelques exceptions 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 exporté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 exportés de cette page.

Exemple

Cet exemple illustre la façon dont les champs de charge utile structurée sont nommés et utilisés lors de l'exportation vers BigQuery.

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

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

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

  • Les champs jsonPayload et name_a sont structurés, mais ils ne contiennent pas de spécificateurs @type. Leurs noms BigQuery correspondent donc respectivement à jsonPayload et name_a.

  • Les champs sub_a et sub_b ne sont pas structurés. Leurs noms BigQuery correspondent donc respectivement à sub_a et sub_b.

  • Le champ name_b contient un spécificateur @type pour lequel [TYPE] a la valeur google.cloud.v1.SubType. Par conséquent, son nom BigQuery est name_b_google_cloud_v1_subtype.

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

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

Champs dans les journaux d'audit exportés

Si vous ne travaillez pas avec des journaux d'audit exporté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 exporté correspondant 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 exportations de journaux vers BigQuery.

Lorsque vous exportez des journaux vers un ensemble de données BigQuery, Stackdriver Logging crée des tables pour conserver les entrées de journaux exportées. Stackdriver Logging utilise deux types de tables pour organiser les données exportées : 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 exportées sont insérées dans des tables BigQuery dont le nom est basé sur le nom des entrées de journal et sur leur horodatage.

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 exporter 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, accédez à la page Exporter des entrées de journal à l'aide de la visionneuse de journaux.

Pour obtenir des instructions sur l'utilisation du SDK Cloud ou de l'interface de ligne de commande, accédez à la page gcloud alpha logging sinks create.

Incohérences dans le schéma

La première entrée de journal exportée 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. Toutefois, si le type de valeur 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 votre exportation initiale contient une entrée de journal dont la valeur de jsonPayload.user_id 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 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.

Stackdriver Logging communique cette perte de données pour le projet Google Cloud contenant l'exportation 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 de l'exportation.
  • 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 de l'exportation, 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é exporté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, reportez-vous à la page Mettre à jour des récepteurs.

Afficher les journaux

Pour afficher vos journaux à l'aide de l'interface utilisateur Web de BigQuery, sélectionnez une table contenant les entrées de journal exportées.