BigQuery-Schema für Logs

Auf dieser Seite werden die Formatierung und die Regeln beschrieben, die beim Weiterleiten von Logeinträgen von Cloud Logging an BigQuery gelten.

Übersicht

Sie können Logeinträge von Cloud Logging mithilfe von Senken an BigQuery weiterleiten. Definieren Sie beim Erstellen einer Senke ein BigQuery-Dataset als Ziel. Logging sendet Logeinträge, die den Regeln der Senke entsprechen, an partitionierte Tabellen, die in diesem BigQuery-Dataset für Sie erstellt werden.

BigQuery-Tabellenschemas für Daten, die von Cloud Logging empfangen werden, basieren auf der Struktur des LogEntry-Typs und den Inhalten der Logeintragsnutzlasten. In Cloud Logging werden außerdem Regeln angewendet, um die Feldnamen des BigQuery-Schemas für Audit-Logs und für bestimmte strukturierte Nutzlastfelder zu kürzen.

Logging streamt in kleinen Batches Logging-Daten in BigQuery, sodass Sie Daten abfragen können, ohne einen Ladejob auszuführen. Weitere Informationen finden Sie unter Daten in BigQuery streamen. Preisinformationen finden Sie im Abschnitt "Streaming-Insert-Anweisungen" unterBigQuery-Preise: Preise für die Datenaufnahme aus.

Warnung: Wenn Sie Logging-Senken verwenden, um Logeinträge an BigQuery weiterzuleiten, treten möglicherweise fehlende Logeinträge in BigQuery auf, wenn die Schemas nicht übereinstimmen. Weitere Informationen finden Sie unter Nicht übereinstimmend im Schema.

Namenskonventionen für Felder

Für das Senden von Logs an BigQuery gelten einige Namenskonventionen:

• Die Namen der Felder für den Logeintrag dürfen nicht länger als 128 Zeichen sein.

• Die Feldnamen für Logeinträge dürfen nur alphanumerische Zeichen enthalten. Alle nicht unterstützten Zeichen werden aus Feldnamen entfernt und durch Unterstrich ersetzt. Beispiel: jsonPayload.foo%% wird in jsonPayload.foo__ umgewandelt.

  Die Namen der Logeintragsfelder müssen auch nach der Transformation mit einem alphanumerischen Zeichen beginnen. alle führenden Unterstriche werden entfernt.

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

• Bei allen vom Nutzer bereitgestellten Logeintragsfeldern werden die entsprechenden BigQuery-Feldnamen in Kleinbuchstaben umgewandelt, die Benennung bleibt jedoch ansonsten erhalten.

• Bei Feldern in strukturierten Nutzlasten werden, solange der Spezifizierer @type nicht vorhanden ist, die entsprechenden BigQuery-Feldnamen in Kleinbuchstaben umgewandelt. Die Benennung wird ansonsten beibehalten.

  Informationen zu strukturierten Nutzlasten, in denen der Spezifizierer @type vorhanden ist, finden Sie auf dieser Seite unter Nutzlastfelder mit @type.

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

Logeintragsfeld	LogEntry-Typenzuordnung	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

Nutzlastfelder mit @type

In diesem Abschnitt werden spezielle BigQuery-Schemafeldnamen für Logeinträge erläutert, deren Nutzlasten den Spezifizierer @type enthalten. Dies gilt auch für an BigQuery weitergeleitete Audit-Logeinträge.

Nutzlasten in Logeinträgen können strukturierte Daten enthalten. Jedes strukturierte Feld kann einen optionalen Typspezifizierer im folgenden Format enthalten:

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

Die Benennungsregeln erklären, warum das Feld protoPayload eines Audit-Logeintrags möglicherweise dem BigQuery-Schemafeld protopayload_auditlog zugeordnet wird.

Benennungsregeln für @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.

Die Benennungsregeln für @type gelten nur für die oberste Ebene von jsonPayload oder protoPayload. verschachtelte Felder werden ignoriert. Wenn die strukturierten Nutzlastfelder der obersten Ebene behandelt werden, entfernt Logging das Präfix type.googleapis.com.

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	(–)	statusCode	protoPayload.statuscode
protoPayload	type.googleapis.com/abc.Xyz	statusCode	protopayload_abc_xyz.statuscode

Für die obigen Regeln für Felder mit Typspezifizierern gelten einige Ausnahmen:

• In App Engine-Anfragelogs lautet der Name der Nutzlast in an BigQuery weitergeleiteten Logs protoPayload, obwohl die Nutzlast einen Typspezifizierer enthält.

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

Beispiel

Dieses Beispiel zeigt, wie strukturierte Nutzlastfelder benannt und verwendet werden, wenn sie von BigQuery empfangen werden.

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

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

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

• Das strukturierte Feld jsonPayload der obersten Ebene enthält den Bezeichner @type. Der BigQuery-Name ist jsonpayload_v1_customtype.

• Die verschachtelten Felder werden mit den standardmäßigen BigQuery-Benennungsregeln behandelt, da für verschachtelte Felder keine Typspezifizierer-Regeln gelten.

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

  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

Felder in exportierten Audit-Logs

Wenn Sie nicht mit Audit-Logs arbeiten, die an BigQuery weitergeleitet 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 für Audit-Logs spezifisch ist, die von BigQuery generiert und dann von Cloud Logging an BigQuery weitergeleitet werden. Diese Audit-Logeinträge enthalten das Feld serviceData mit dem @type-Spezifizierer type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Beispiel

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

protoPayload.serviceData.tableInsertRequest

Wie würde das Feld tableInsertRequest referenziert, wenn dieser Logeintrag dann an BigQuery weitergeleitet wird? Vor der Namenskürzung lautet der entsprechende Feldname in BigQuery:

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 bietet eine Übersicht über partitionierte Tabellen für Logs, die an BigQuery weitergeleitet werden.

Wenn Sie Logs an ein BigQuery-Dataset weiterleiten, erstellt Logging Tabellen, um die Logeinträge zu speichern. Es gibt zwei Tabellentypen, mit denen Logging die weitergeleiteten Daten organisiert: nach Datum fragmentierte Tabellen und partitionierte Tabellen. Beide Tabellentypen partitionieren die Logdaten basierend auf den timestamp-Feldern der Logeinträge. Zwischen den Tabellentypen gibt es jedoch zwei Hauptunterschiede:

• Leistung: Eine partitionierte Tabelle unterteilt eine große Tabelle in kleinere Partitionen, damit Sie die Abfrageleistung verbessern und somit Ihre BigQuery-Kosten besser kontrollieren können. Dazu reduzieren Sie die Anzahl der von einer Abfrage gelesenen Byte.

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

Tabellenorganisation

Logeinträge werden in BigQuery-Tabellen aufgeteilt, deren Organisation und Namen auf den Lognamen und Zeitstempeln der Einträge basieren.

Die Tabellennamen haben das Kalenderdatum des UTC-Zeitstempels des Logeintrags im einfachen ISO 8601-Format (JJJJMMTT).

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

Beim Erstellen einer Senke zum Weiterleiten Ihrer Logs an BigQuery können Sie entweder nach Datum fragmentierte Tabellen oder partitionierte Tabellen verwenden. Die Standardauswahl sind nach Datum fragmentierte Tabellen.

Eine Anleitung zur Verwendung der Google Cloud Console finden Sie unter Senken konfigurieren.

Eine Anleitung zum Verwenden des Cloud SDK, der Befehlszeile, finden Sie unter gcloud logging sinks create.

Abweichungen im Schema

Der erste von BigQuery empfangene Logeintrag bestimmt das Schema für die BigQuery-Zieltabelle. BigQuery erstellt eine Tabelle, deren Spalten auf den Feldern des ersten Logeintrags und ihren Typen basieren.

Ein Schemakonflikt tritt auf, wenn Logeinträge in die Zieltabelle geschrieben werden und einer der folgenden Fehler auftritt:

• In einem späteren Logeintrag wird der Feldtyp für ein vorhandenes Feld in der Tabelle geändert.

  Wenn beispielsweise das Feld jsonPayload.user_id des ersten Logeintrags ein string ist, generiert dieser Logeintrag eine Tabelle mit einem Stringtyp für dieses Feld. Wenn Sie später damit beginnen, jsonPayload.user_id als array zu protokollieren, führt dies zu einer Schemaabweichung.

• Einem Logeintrag werden neue Felder hinzugefügt, wodurch die Anzahl der Spalten in der Zieltabelle das BigQuery-Spaltenlimit überschreitet. Weitere Informationen zum Spaltenlimit finden Sie unter BigQuery-Kontingente und -Limits.

Wenn BigQuery ein Schemakonflikt feststellt, wird eine Tabelle im entsprechenden Dataset zur Speicherung der Fehlerinformationen erstellt. Der Tabellentyp bestimmt den Tabellennamen. Für datumsfragmentierte Tabellen ist das Format export_errors_YYYYMMDD und für partitionierte Tabellen das Format export_errors. Weitere Informationen finden Sie unter Tabellenorganisation.

Beim Exportieren von Logeinträgen sendet Logging Nachrichten als Batch an BigQuery. BigQuery verwendet die folgenden Regeln, um zu bestimmen, in welche Tabelle die Logeinträge im aktuellen Batch der Nachrichten geschrieben werden:

• Wenn ein Feldtyp geändert wird, werden nur die Logeinträge, die zu einem Schemakonflikt geführt haben, in die Fehlertabelle geschrieben. Logeinträge im aktuellen Batch von Nachrichten, die nicht zu einer Schemaabweichung führen, werden in die ursprüngliche Zieltabelle geschrieben.

• Wenn das Spaltenlimit überschritten wird, werden alle Logeinträge im aktuellen Batch von Nachrichten in die Fehlertabelle geschrieben.

Die Fehlertabelle enthält Daten aus dem LogEntry und Informationen zu den nicht übereinstimmenden Daten:

• LogEntry-Felder in die Fehlertabelle schreiben:

  • logName
  • timestamp
  • receiveTimestamp
  • severity
  • insertId
  • trace
  • resource.type

• In die Fehlertabelle geschriebene Informationen zur Schemaabweichung:

  • Vollständiger Ressourcenpfad für die Logsenke
  • Die vollständige Fehlermeldung, die von BigQuery zurückgegeben wird
  • Den vollständigen Logeintrag Der Logeintrag wird jedoch von JSON in einen String konvertiert.

Logging meldet nicht übereinstimmende Schemaabweichungen mit dem Cloud-Projekt, das die Routingsenke enthält:

• Projektinhaber erhalten eine E-Mail. Details: Google Cloud-Projekt-ID, Name der Senke und Ziel.
• In der Google Cloud Console wird auf der Seite "Aktivität" der Fehler Stackdriver Config error angezeigt. Details sind der Name und das Ziel der Senke sowie ein Link zu einem Beispiel für einen Logeintrag, der den Fehler verursacht hat.
• Der logbasierte Systemmesswert exports/error_count informiert Sie über die Gesamtzahl der Logeinträge, die aufgrund von Fehlern nicht weitergeleitet wurden.

Korrigieren Sie den Feldtyp für spätere Logeinträge, indem Sie den Feldtyp so korrigieren, dass er dem aktuellen Schema entspricht. 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 verwalten.

Logs ansehen

Zum Aufrufen der Logs und des zugehörigen BigQuery-Schemas wählen Sie in der BigQuery-Web-UI eine Tabelle aus, die Logeinträge von Cloud Logging erhalten hat.