Auf dieser Seite werden die Formatierung sowie die Regeln erläutert, die bei der Weiterleitung von Logeinträgen von Cloud Logging nach BigQuery gelten.
Übersicht
Sie können Logeinträge von Cloud Logging mithilfe von Senken an BigQuery weiterleiten. Wenn Sie eine Senke erstellen, definieren Sie ein BigQuery-Dataset als Ziel. Logging sendet Logeinträge, die den Regeln der Senke entsprechen, an partitionierte Tabellen, die in diesem BigQuery-Dataset erstellt werden.
BigQuery-Tabellenschemas für Daten, die von Cloud Logging empfangen werden, basieren auf der Struktur des Typs LogEntry und dem Inhalt der Nutzlasten des Logeintrags. Cloud Logging wendet auch Regeln zum Kürzen der BigQuery-Schemafeldnamen für Audit-Logs und für bestimmte strukturierte Nutzlastfelder an.
Logging-Senken streamen Logging-Daten in kleinen Batches nach 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" unter BigQuery-Preise: Preise für die Datenaufnahme.
Namenskonventionen für Felder
Für das Senden von Logs an BigQuery gelten einige Namenskonventionen für Logeintragsfelder:
Die Namen der Felder für Logeinträge dürfen 128 Zeichen nicht überschreiten.
Feldnamen von Logeinträgen dürfen nur alphanumerische Zeichen enthalten. Nicht unterstützte Zeichen werden aus Feldnamen entfernt und durch Unterstriche ersetzt. Beispielsweise würde
jsonPayload.foo%%
injsonPayload.foo__
umgewandelt werden.Die Namen der Logeintragsfelder müssen auch nach der Transformation mit einem alphanumerischen Zeichen beginnen. Alle vorangestellten Unterstriche werden entfernt.
Bei Logeintragsfeldern, die zum Typ LogEntry gehören, sind die BigQuery-Tabellennamen mit den Namen der Logeintragsfelder identisch.
Bei vom Nutzer angegebenen Logeintragsfeldern werden die entsprechenden BigQuery-Feldnamen in Kleinbuchstaben umgewandelt. Ansonsten bleibt die Benennung erhalten.
Bei Feldern in strukturierten Nutzlasten werden die entsprechenden BigQuery-Feldnamen, falls der
@type
-Bezeichner nicht vorhanden ist, in Kleinbuchstaben umgewandelt. Ansonsten bleibt die Benennung erhalten.Informationen zu strukturierten Nutzlasten, bei denen der
@type
-Bezeichner 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 BigQuery-Schemafeldnamen für Logeinträge beschrieben, deren Nutzlasten den Bezeichner @type
enthalten. Dies gilt auch für Audit-Logeinträge, die an BigQuery weitergeleitet werden.
Nutzlasten in Logeinträgen können strukturierte Daten enthalten. Jedes strukturierte Feld kann einen optionalen Typbezeichner im folgenden Format enthalten:
@type: type.googleapis.com/[TYPE]
Benennungsregeln erklären, warum das protoPayload
-Feld eines Audit-Logeintrags dem BigQuery-Schemafeld protopayload_auditlog
zugeordnet werden kann.
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. Bei der Behandlung von strukturierten Nutzlastfeldern der obersten Ebene 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 |
(keine) | statusCode |
protoPayload.statuscode |
protoPayload |
type.googleapis.com/abc.Xyz |
statusCode |
protopayload_abc_xyz.statuscode |
Für Felder mit Typbezeichnern gelten einige Ausnahmen der vorhergehenden Regeln:
In Anfragelogs von App Engine lautet der Name der Nutzlast in zu BigQuery weitergeleiteten 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 Audit-Log-Felder auf dieser Seite erläutert.
Beispiel
Dieses Beispiel zeigt, wie strukturierte Nutzdatenfelder beim Empfang durch BigQuery benannt und verwendet werden.
Angenommen, die Nutzlast eines Log-Eintrags ist so 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 übergeordnete strukturierte Feld
jsonPayload
enthält den Spezifizierer@type
. Der BigQuery-Name lautetjsonpayload_v1_customtype
.Die verschachtelten Felder werden gemäß der standardmäßigen BigQuery-Benennungsregeln behandelt, da Regeln für Typbezeichner nicht für verschachtelte Felder gelten.
Daher sind folgende 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
Audit-Logs-Felder
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
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-Log-Einträge beinhalten ein Feld mit folgendem Namen:
protoPayload.serviceData.tableInsertRequest
Wie wird auf das Feld tableInsertRequest
verwiesen, wenn dieser Logeintrag zu BigQuery weitergeleitet wird? Der entsprechende Feldname in BigQuery 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 Logs, die an BigQuery weitergeleitet werden.
Wenn Sie Logs an ein BigQuery-Dataset weiterleiten, erstellt Logging Tabellen für die Logeinträge. Es gibt zwei Tabellentypen, mit denen Logging die weitergeleiteten 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
Logeinträge werden in BigQuery-Tabellen aufgeteilt, deren Organisation und Namen auf den Lognamen und Zeitstempeln der Einträge beruhen.
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
Wenn Sie eine Senke zum Weiterleiten Ihrer Logs in BigQuery erstellen, 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 und verwalten.
Eine Anleitung zur Verwendung der Google Cloud CLI 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 nach den Feldern und den Typen des ersten Logeintrags benannt werden.
Ein Schemakonflikt tritt auf, wenn Logeinträge in die Zieltabelle geschrieben werden und einer der folgenden Fehler auftritt:
Ein späterer Logeintrag ändert den Feldtyp eines in der Tabelle vorhandenen Felds.
Wenn das Feld
jsonPayload.user_id
des ersten Logeintrags beispielsweise einstring
ist, generiert dieser Logeintrag eine Tabelle mit einem Stringtyp für dieses Feld. Wenn Sie späterjsonPayload.user_id
alsarray
loggen, führt dies zu einer Schemaabweichung.Ein neuer Logeintrag enthält ein Feld, das im aktuellen Schema nicht vorhanden ist. Wenn Sie dieses Feld in die Zieltabelle einfügen, würde das BigQuery-Spaltenlimit überschritten werden.
Die Zieltabelle kann das neue Feld akzeptieren, wenn es nicht dazu führt, dass das Spaltenlimit überschritten wird.
Wenn BigQuery ein nicht übereinstimmendes Schema identifiziert, wird eine Tabelle im entsprechenden Dataset erstellt, um die Fehlerinformationen zu speichern. Ein Tabellentyp legt den Tabellennamen fest. Bei datumsfragmentierten Tabellen lautet das Namensformat export_errors_YYYYMMDD
. Für partitionierte Tabellen lautet das Namensformat export_errors
. Weitere Informationen finden Sie unter Tabellenorganisation.
Beim Weiterleiten 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 von Nachrichten geschrieben werden:
Wenn eine Feldtypänderung auftritt, werden nur die Logeinträge in die Fehlertabelle geschrieben, die eine Schemaabweichung verursacht haben. Logeinträge im aktuellen Batch von Nachrichten, die keine Schemaabweichungen verursachen, werden in die ursprüngliche Zieltabelle geschrieben.
Wird das Spaltenlimit überschritten, werden alle Logeinträge im aktuellen Nachrichten-Batch in die Fehlertabelle geschrieben.
Die Fehlertabelle enthält Daten aus dem LogEntry und Informationen zur Abweichung:
LogEntry-Felder, die in die Fehlertabelle geschrieben werden:
logName
timestamp
receiveTimestamp
severity
insertId
trace
resource.type
In die Fehlertabelle geschriebene Informationen zur Schemaabweichungen:
- Vollständiger Ressourcenpfad für die Logsenke
- Die vollständige Fehlermeldung, die von BigQuery zurückgegeben wird
- Der vollständige Logeintrag. Der Logeintrag wird jedoch von JSON in einen String konvertiert.
Logging kommuniziert dem Cloud-Projekt, das die Routing-Senke enthält, Schemaabweichungen auf folgende Weise:
- Projektinhaber erhalten eine E-Mail. Darin werden die Google Cloud-Projekt-ID, der Name der Senke und das Exportziel angegeben.
- Auf der Seite „Aktivität“ der Google Cloud Console wird der Fehler „
Stackdriver Config error
“ angezeigt. Die Detailangaben enthalten den Namen der Senke und das Exportziel sowie einen Link zu einem Beispiel für einen den Fehler auslösenden Logeintrag. - 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 so, dass er mit dem aktuellen Schema übereinstimmt. So korrigieren Sie Feldabweichungen für spätere Logeinträge. 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 finden Sie unter Senken konfigurieren und verwalten.
Logs ansehen
Eine Anleitung zum Aufrufen der weitergeleiteten Logs in BigQuery finden Sie unter Logs in Senkenzielen ansehen.