Schéma BigQuery des journaux exportés

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. Stackdriver 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 un schéma de table depuis l'interface utilisateur Web de BigQuery en sélectionnant une table comportant des entrées de journal exportées.

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 l'indicateur @type n'apparaît pas, la casse des lettres est normalisée en minuscules, mais la dénomination est préservée.

      Pour en savoir plus sur les charges utiles structurées contenant l'indicateur @type, consultez la section 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 avec les noms de champs BigQuery est plus complexe lorsque le champ structuré contient un indicateur @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 indicateurs 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é avec le champ protopayload_auditlog d'un schéma BigQuery.

Il existe actuellement deux schémas pour les entrées de journal d'audit dans BigQuery. Par deux schémas, nous entendons que certaines informations relatives aux charges utiles de journal d'audit sont actuellement dupliquées dans deux champs BigQuery distincts, contenant les informations dans deux différents formats : un ancien nom de champ "étendu" et un nouveau nom de champ "compact". Le 1er mars 2019, l'ancien schéma (noms de champs) sera supprimé. Pour en savoir plus, consultez la section Migration vers un schéma mis à jour ci-dessous.

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 indicateurs 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 alors mappés de la façon suivante :

  • Si le champ structuré imbriqué ne contient pas d'indicateur @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 indicateur @type, son nom de champ BigQuery est suivi d'un [TYPE] (réécrit). Ce nom est par ailleurs 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 dans BigQuery est protoPayload, même si elle possède un indicateur de type. Pour consulter un exemple de requête concernant les journaux App Engine, accédez à la section Requêtes.

  • Stackdriver 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 suivante Champs de schémas de journaux d'audit.

  • Les journaux d'audit exportés vers BigQuery sont écrits dans un format compact mis à jour. Certaines informations relatives aux charges utiles sont temporairement dupliquées dans deux champs différents. Pour plus d'informations, consultez la section relative à la migration vers un schéma à jour.

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 d'indicateurs @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 possède un indicateur @type pour lequel [TYPE] a la valeur google.cloud.v1.SubType. Son nom BigQuery correspond donc à 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 de schémas de 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 anciens champs de charge utile ("étendus") de journaux d'audit possèdent tous des indicateurs de type (champs @type) dans Stackdriver. Leurs noms de champs BigQuery correspondants sont spécialement conçus pour ne pas être trop longs.

Les nouveaux champs de charge utile ("compacts") de journal d'audit, protoPayload.request, protoPayload.response et protoPayload.metadata, possèdent des indicateurs @type mais sont traités comme des données JSON. Autrement dit, leurs noms de schéma BigQuery correspondent à leurs noms de champs 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 étendu (ancien) Nom de champ BigQuery compact (nouveau)
protoPayload protopayload_auditlog Identique
protopayload.metadata protopayload_auditlog.metadata_* protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
Exemple : protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
Identique
protoPayload.request protopayload_auditlog.request_[Vn]_[PROTO_NAME]
Exemple : protopayload_auditlog.request_v2_listlogsinksrequest
protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.response_[Vn]_[PROTO_NAME]
Exemple : protopayload_auditlog.response_v2_listlogsinksresponse
protopayload_auditlog.responseJson

Vous devez réviser vos requêtes pour utiliser le nouveau schéma compact (noms de champs) avant le 1er mars 2019, lorsque l'ancien schéma étendu (noms de champs) sera supprimé.

Prenez en compte les informations suivantes sur la dénomination des journaux d'audit :

  • La règle de dénomination de serviceData est spécifique aux journaux d'audit qui sont générés par BigQuery, puis exportés vers BigQuery. Ces entrées de journaux d'audit contiennent un champ serviceData possédant l'indicateur @type suivant :

    type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
    
  • Les règles de dénomination relatives aux champs étendus (anciens) request et response supposent que leurs indicateurs de type suivent un modèle commun :

    [GOOGLE_SERVICE].[Vn].[PROTO_NAME]
    

    Par exemple, l'indicateur d'un champ request pourrait être :

    google.logging.v2.ListLogSinksRequest
    

    Une fois les points remplacés par des traits de soulignement et le texte mis en minuscules, le nom de champ habituel suivant apparaît :

    request_google_logging_v2_listlogsinksrequest
    

    Le nom spécialement créé du champ de schéma est le suivant :

    request_v2_listlogsinksrequest
    

    Si vous rencontrez un indicateur de type dans un autre format, examinez certaines des entrées de journal exportées pour identifier la façon dont les noms de champs exportés sont raccourcis.

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

Migration vers un schéma mis à jour

Il existe actuellement deux ensembles de noms de champs, "étendu" et "compact", pour les entrées de journal d'audit dans BigQuery. Le 1er mars 2019, les ensembles étendus de noms de champs seront supprimés. Examinez vos requêtes et déterminez si vous devez migrer vers le nouvel ensemble de noms de champs :

  • Si vous n'utilisez pas actuellement les champs request, response ou requestMetadata des journaux d'audit exportés dans des requêtes BigQuery, cette migration ne vous concerne pas. Vous pouvez ignorer cette section.

  • Si vous utilisez les champs request, response ou requestMetadata pour la première fois, utilisez les (nouveaux) noms compacts dès le départ. Tous les journaux d'audit produits pour de nouveaux services utiliseront uniquement le nouveau format compact. Vous pouvez ignorer cette section.

  • Si vous utilisez les champs request, response ou requestMetadata des journaux d'audit exportés dans des requêtes BigQuery et si vous utilisez les (anciens) noms de champs étendus, passez aux (nouveaux) noms compacts dès que possible. Lisez cette section et consultez la section Mettre à jour vos requêtes pour obtenir un exemple de mise à jour de vos requêtes.

Cette modification affecte à la fois les journaux d'audit des activités d'administration et de l'accès aux données, en les transformant du format étendu actuel, contenant un nombre arbitraire de champs, en un format JSON compact et mis à jour. Pour les journaux d'audit existants, Stackdriver Logging utilise déjà le nouveau format compact :

Schéma compact

Vous pourrez voir les deux formats dans BigQuery jusqu'au 1er mars 2019, date à laquelle le format étendu sera supprimé.

Les exportations de journaux non relatifs à un audit ne sont pas affectées. Les exportations de journaux d'audit vers des emplacements autres que BigQuery ne sont pas affectées.

Mettre à jour vos requêtes

La table présentée dans la section Champs de schémas de journaux d'audit répertorie les champs affectés par la modification du nom de champ étendu en nom de champ compact. Si vous interrogez l'un de ces champs, vous devez examiner vos requêtes BigQuery et les réviser si nécessaire avant le 1er mars 2019, date à laquelle les anciens champs seront supprimés.

Pour mettre à jour vos requêtes, vous devez utiliser la méthode BigQuery JSON_EXTRACT(). L'indicateur @type dans ces champs doit être traité comme une description du contenu des données JSON.

À titre d'exemple, voici à quoi pourrait ressembler une requête permettant de sélectionner l'un des champs createSinkRequest, avec les noms de champ étendus :

 SELECT protopayload_auditlog.request_v2_createsinkrequest.sink.destination
 as dest FROM ...

Lorsque les noms de champs seront compacts, la syntaxe ressemblera à ceci :

SELECT JSON_EXTRACT(protopayload_auditlog.requestJson, '$.sink.destination')
as dest FROM ...

Consulter vos journaux d'audit

Pour les journaux d'audit existants, Stackdriver Logging utilise à la fois le nouveau format compact et l'ancien format étendu. Vous pourrez voir les deux formats dans BigQuery jusqu'au 1er mars 2019, date à laquelle le format étendu sera supprimé.

Pour consulter vos journaux d'audit depuis l'UI Web de BigQuery, sélectionnez une table comportant les entrées de journal exportées.

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Stackdriver Logging
Besoin d'aide ? Consultez notre page d'assistance.