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 Log-Nutzlasten. 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-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 |
Wenn das strukturierte Feld den Bezeichner @type
enthä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.
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
undname_a
sind strukturiert, haben aber keine@type
-Bezeichner. Die BigQuery-Namen lautenjsonPayload
bzw.name_a
.Die Felder
sub_a
undsub_b
sind nicht strukturiert. Daher lauten ihre BigQuery-Namensub_a
bzw.sub_b
.Das Feld
name_b
hat einen@type
-Bezeichner, dessen [TYPE]google.cloud.v1.SubType
ist. Daher lautet der BigQuery-Namename_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 fragmentiert, 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 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.
Anleitungen zur Verwendung der Google Cloud Console finden Sie unter Export über den Log-Explorer.
Eine Anleitung zur Verwendung der Befehlszeile des Cloud SDK finden Sie unter gcloud 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.