BigQuery-Schema für exportierte Logs

Auf dieser Seite werden die Formatierung sowie die Regeln erläutert, die beim Exportieren von Logeinträgen aus Cloud Logging in BigQuery gelten.

Logging streamt Logging-Daten einzeln in BigQuery, anstatt Ladejobs zu verwenden. Bei dieser Vorgehensweise können Sie Daten in BigQuery ohne die Verzögerung abfragen, die durch die Ausführung eines Ladejobs entsteht. Weitere Informationen finden Sie unter Daten in BigQuery streamen.

BigQuery-Tabellenschemas für exportierte Logs basieren auf der Struktur des LogEntry-Typs und den Inhalten der Lognutzlasten. Für Cloud Logging gelten außerdem einige Sonderregeln zum Kürzen von BigQuery-Schemafeldnamen für Audit-Logs. Sie können das Tabellenschema aufrufen, indem Sie in der BigQuery-Web-UI eine Tabelle mit exportierten Logeinträgen auswählen.

Namenskonventionen für Felder

Für die Benennung von Logeintragsfeldern gelten einige Konventionen:

• Bei Logeintragsfeldern, die zum Typ LogEntry gehören, sind die BigQuery-Tabellennamen mit den Namen der Logeintragsfelder identisch.

• Bei vom Nutzer angegebenen Feldern wird einheitlich die Kleinschreibung verwendet. Ansonsten bleibt die Benennung erhalten.

  • Bei Feldern in strukturierten Nutzlasten wird, wenn der Bezeichner @type nicht vorhanden ist, einheitlich die Kleinschreibung verwendet. Ansonsten bleibt die Benennung erhalten.

    Informationen zu strukturierten Nutzlasten, bei denen der Bezeichner @type vorhanden ist, finden Sie unter Nutzlastfelder mit @type.

Die folgenden Beispiele zeigen, wie die Konventionen zur Benennung angewendet werden:

Logeintragsfeld	LogEntry-Typzuordnung	BigQuery-Feldname
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

Wenn das strukturierte Feld den Bezeichner @typeenthält, ist die Zuordnung von Feldern strukturierter Nutzlasten zu BigQuery-Feldnamen komplexer. Darauf wird im folgenden Abschnitt eingegangen.

Nutzlastfelder mit @type

In diesem Abschnitt werden BigQuery-Schemafeldnamen für Logeinträge beschrieben, deren Nutzlasten Typbezeichner (@type-Felder) enthalten. Dies betrifft alle exportierten Audit-Logeinträge in BigQuery. Beispielsweise wird in diesem Abschnitt erläutert, warum das Feld protoPayload eines Audit-Logeintrags dem BigQuery-Schemafeld protopayload_auditlog zugeordnet werden kann.

Schemabenennungsregeln

Nutzlasten in Log-Einträgen können strukturierte Daten umfassen, die wiederum verschachtelte strukturierte Felder enthalten können. Jedes strukturierte Feld kann einen optionalen Typbezeichner im folgenden Format enthalten:

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

Strukturierte Felder mit Typspezifizierern erhalten normalerweise BigQuery-Feldnamen, an die ein [TYPE] angehängt ist. Der Wert von [TYPE] kann ein beliebiger String sein.

Hinweis: Beim Logging wird das Präfix type.googleapis.com aus Ihren Nutzlasten entfernt.

Die folgende Tabelle zeigt beispielsweise die Zuordnung der obersten strukturierten Nutzlastfelder zu BigQuery-Feldnamen:

Nutzlast	Nutzlast @type	Nutzlastfeld	BigQuery-Feldname
jsonPayload	(keine)	statusCode	jsonPayload.statusCode
jsonPayload	type.googleapis.com/abc.Xyz	statusCode	jsonPayload_abc_xyz.statuscode
protoPayload	(keine)	statusCode	protoPayload.statuscode
protoPayload	type.googleapis.com/abc.Xyz	statusCode	protopayload_abc_xyz.statuscode

Wenn jsonPayload oder protoPayload andere strukturierte Felder enthält, werden diese verschachtelten Felder so zugeordnet:

• Wenn das verschachtelte strukturierte Feld nicht den Bezeichner @type hat, ist der BigQuery-Feldname bis auf die durchgängige Kleinschreibung mit dem Originalfeldnamen identisch.
• Wenn das verschachtelte strukturierte Feld den Bezeichner @type hat, wird an den BigQuery-Feldnamen [TYPE] (in entsprechender Schreibweise) angehängt und der Feldname wird durchgängig kleingeschrieben.

Es gibt von den vorhergehenden Regeln für Felder mit Typbezeichnern einige Ausnahmen:

• In Anfragelogs von App Engine lautet der Name der Nutzlast in zu BigQuery exportierten Logs protoPayload, obwohl die Nutzlast einen Typbezeichner hat.

• Für Cloud Logging gelten einige Sonderregeln zum Kürzen von BigQuery-Schemafeldnamen für Audit-Logs. Dies wird im Abschnitt Exportierte Audit-Log-Schemafelder auf dieser Seite erläutert.

Beispiel

Dieses Beispiel zeigt, wie strukturierte Nutzdatenfelder beim Export zu BigQuery benannt und verwendet werden.

Angenommen, die Nutzlast eines Log-Eintrags ist wie folgt strukturiert:

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

Die Zuordnung zu BigQuery-Feldern wird so durchgeführt:

• Die Felder jsonPayload und name_a sind strukturiert, haben aber keine @type-Bezeichner. Die BigQuery-Namen lauten jsonPayload bzw. name_a.

• Die Felder sub_a und sub_b sind nicht strukturiert. Daher lauten ihre BigQuery-Namen sub_a bzw. sub_b.

• Das Feld name_b hat einen @type-Bezeichner, dessen [TYPE] google.cloud.v1.SubType ist. Daher lautet der BigQuery-Name name_b_google_cloud_v1_subtype.

Insgesamt werden für die Nutzlast des Logeintrags die folgenden fünf BigQuery-Namen definiert:

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

Felder in exportierten Audit-Logs

Wenn Sie nicht mit Audit-Logs arbeiten, die nach BigQuery exportiert wurden, können Sie diesen Abschnitt überspringen.

Die Nutzlastfelder protoPayload.request, protoPayload.response und protoPayload.metadata des Audit-Logs haben @type-Bezeichner, werden jedoch als JSON-Daten behandelt. Das heißt, ihre BigQuery-Schemanamen entsprechen den Feldnamen, an die Json angehängt wird. Sie enthalten außerdem Stringdaten im JSON-Format.

Die zwei Sätze Audit-Log-Nutzlastfeldnamen sind in der folgenden Tabelle aufgeführt:

Logeintragsfeld	BigQuery-Feldname
protoPayload	protopayload_auditlog
protopayload.metadata	protopayload_auditlog.metadataJson
protoPayload.serviceData	protopayload_auditlog.servicedata_v1_bigquery Beispiel: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request	protopayload_auditlog.requestJson
protoPayload.response	protopayload_auditlog.responseJson

Beachten Sie, dass die Namenskonvention serviceData nur für Audit-Logs gilt, die von BigQuery generiert und dann aus Cloud Logging in BigQuery exportiert werden. Diese Audit-Logeinträge enthalten ein Feld serviceData mit dem @type-Bezeichner type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Beispiel

In BigQuery generierte Audit-Logeinträge beinhalten ein Feld mit folgendem Namen:

protoPayload.serviceData.tableInsertRequest

Wie wird auf das Feld tableInsertRequest verwiesen, wenn dieser Logeintrag zu BigQuery exportiert wird? Der entsprechende exportierte Feldname würde vor der Namenskürzung so lauten:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Nach der Namenskürzung wird dasselbe Feld in BigQuery-Tabellen so referenziert:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Partitionierte Tabellen

Dieser Abschnitt enthält eine Übersicht über partitionierte Tabellen für Logexporte nach BigQuery.

Wenn Sie Logs in ein BigQuery-Dataset exportieren, erstellt Logging Tabellen für die exportierten Logeinträge. Es gibt zwei Tabellentypen, mit denen Logging die exportierten Daten organisiert: nach Datum fragmentierte Tabellen und partitionierte Tabellen. Beide Tabellentypen partitionieren die Logdaten nach den timestamp-Feldern der Logeinträge. Es gibt jedoch zwei wichtige Unterschiede zwischen den Tabellentypen:

• Leistung: Eine partitionierte Tabelle teilt eine große Tabelle in kleinere auf. Auf diese Weise können Sie die Abfrageleistung verbessern und die Kosten von BigQuery besser steuern, da die Menge der gelesenen Byte reduziert wird.

• Tabellennomenklatur: Die Tabellentypen verwenden unterschiedliche Namenskonventionen, wie im folgenden Abschnitt erläutert.

Tabellenorganisation

Exportierte Logeinträge werden in BigQuery-Tabellen abgelegt, deren Namen auf den Lognamen und Zeitstempeln der Einträge beruhen.

Die folgende Tabelle zeigt Beispiele dafür, wie Lognamen und beispielhafte Zeitstempel Tabellennamen in BigQuery zugeordnet werden:

Logname	Logeintrag timestamp	BigQuery-Tabellenname (nach Datum fragmentiert)	BigQuery-Tabellenname (partitioniert)
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

Partitionierte Tabellen erstellen

Wenn Sie eine Senke zum Exportieren Ihrer Logs in BigQuery erstellen, können Sie entweder nach Datum fragmentierte Tabellen oder partitionierte Tabellen verwenden. Die Standardauswahl sind nach Datum fragmentierte Tabellen.

Hinweise zur Verwendung der Google Cloud Console finden Sie unter Export über die Loganzeige.

Eine Anleitung zur Verwendung der Befehlszeile des Cloud SDK finden Sie unter gcloud alpha logging sinks create.

Abweichungen im Schema

Der erste exportierte Logeintrag bestimmt das Schema für die BigQuery-Zieltabelle. Der Logeintrag generiert eine Tabelle, deren Spalten nach den Feldern und den Typen des Logeintrags benannt werden. Enthalten nachfolgende Logeinträge neue Felder, wird das Tabellenschema aktualisiert. Ändert sich der Werttyp eines vorhandenen Felds, werden neuere Logeinträge, die nicht mit dem Schema übereinstimmen, ausgelassen.

Wenn Ihr ursprünglicher Export beispielsweise einen Logeintrag enthält, bei dem jsonPayload.user_id ein string ist, erzeugt dieser Logeintrag eine Tabelle mit einem Stringtyp für dieses Feld. Wenn Sie dann jsonPayload.user_id als array protokollieren, werden diese Logeinträge nicht in die Tabelle eingefügt und gehen verloren.

Logging meldet diesen Datenverlust für das Google Cloud-Projekt, das den Export enthält, auf folgende Arten:

• Projektinhaber erhalten eine E-Mail. Darin werden die Google Cloud-Projekt-ID, der Senkenname und das Exportziel angegeben.
• In der Google Cloud Console wird auf der Seite "Aktivität" der Fehler Stackdriver Config error angezeigt. Die Detailangaben enthalten den Namen der Senke und das Exportziel sowie einen Link zu einem Beispiel eines Logeintrags, der den Fehler verursacht hat.
• Der logbasierte Systemmesswert exports/error_count informiert Sie über die Gesamtzahl der Logeinträge, die aufgrund von Fehlern nicht exportiert wurden.

Beheben Sie das Problem für nachfolgende Logeinträge, damit kein weiterer Datenverlust entsteht. Korrigieren Sie dazu den Feldtyp so, dass er mit dem aktuellen Schema übereinstimmt. Sie können die Tabelle auch umbenennen oder die Parameter der Senke ändern, sodass Logging die Tabelle in einem anderen Dataset neu erstellt. Eine Anleitung dazu finden Sie unter Senken aktualisieren.

Logs ansehen

Wählen Sie eine Tabelle mit exportierten Logeinträgen aus, um Ihre Logs in der BigQuery-Web-UI anzusehen.