An BigQuery weitergeleitete Logs ansehen

In diesem Dokument wird erläutert, wie Sie Logeinträge finden, die Sie von Cloud Logging an BigQuery-Tabellen weitergeleitet haben. Logging-Senken Logging-Daten in BigQuery streamen in kleinen Batches auf, sodass Sie Daten abfragen können, ohne einen Ladejob auszuführen. Um Ihnen beim Erstellen von Abfragen und beim Verstehen des Formats Ihrer BigQuery-Tabelle zu helfen, wird in diesem Dokument auch das BigQuery-Schema für weitergeleitete Protokolle beschrieben.

Cloud Logging verwendet die alte Streaming API, um Ihre Logeinträge an BigQuery zu streamen. Normalerweise sind Logeinträge innerhalb einer Minute in BigQuery zu sehen. Nach dem Erstellen einer neuen Tabelle kann es jedoch einige Minuten dauern, bis der sind erste Logeinträge verfügbar.

Hinweis

Eine konzeptionelle Erörterung von Senken finden Sie unter Übersicht über Routing- und Speichermodelle: Senken.

Anweisungen zum Weiterleiten Ihrer Logs finden Sie unter Logs an unterstützte Ziele weiterleiten

Wie die weitergeleiteten Felder mit Logeinträgen benannt werden, erfahren Sie im BigQuery-Schema für weitergeleitete Logs.

Logs ansehen

So rufen Sie die an BigQuery weitergeleiteten Logs auf:

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery:

    Zu BigQuery Studio

    Sie können diese Seite auch über die Suchleiste finden.

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie ein Dataset aus.

    Die Logeinträge werden auf dem Tab Details angezeigt. Sie können auch die Tabelle nach den Daten abfragen.

Beispielabfragen

Weitere Informationen zur BigQuery-Abfragesyntax finden Sie in der Abfragereferenz. Besonders nützlich sind Tabellenplatzhalterfunktionen, mit der Sie Abfragen in mehreren Tabellen ausführen können. Flatten-Operator, mit dem Sie Daten aus wiederkehrenden Feldern anzuzeigen.

Beispiel für eine Compute Engine-Abfrage

Mit der folgenden BigQuery-Abfrage werden Logeinträge von mehreren Tagen und Logtypen abgerufen:

  • Die Abfrage durchsucht die letzten drei Tage der Logs syslog und apache-access. Die Abfrage wurde am 23. Februar 2020 durchgeführt und deckt alle am 21. und 22. Februar empfangenen Logeinträge sowie die am 23. Februar bis zur Ausgabe der Abfrage erhaltenen Logeinträge ab.

  • Mit der Abfrage werden nur Ergebnisse für die Compute Engine-Instanz 1554300700000000000 abgerufen.

SELECT
  timestamp AS Time,
  logName as Log,
  textPayload AS Message
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.syslog_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())),
  (TABLE_DATE_RANGE(my_bq_dataset.apache_access_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP()))
WHERE
  resource.type == 'gce_instance'
  AND resource.labels.instance_id == '1554300700000000000'
ORDER BY time;

Hier ein paar Beispiele zu Ausgabezeilen:

Row | Time                    | Log                                         | Message
--- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------
 5  | 2020-02-21 03:40:14 UTC | projects/project-id/logs/syslog             | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269;
 6  | 2020-02-21 04:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 7  | 2020-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2020:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2020-02-21 05:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 9  | 2020-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2020:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

Beispiel für eine App Engine-Abfrage

Mit der folgenden BigQuery-Abfrage werden Logeinträge von fehlgeschlagenen App Engine-Anfragen des vergangenen Monats abgerufen:

SELECT
  timestamp AS Time,
  protoPayload.host AS Host,
  protoPayload.status AS Status,
  protoPayload.resource AS Path
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_,
    DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP()))
WHERE
  protoPayload.status != 200
ORDER BY time

Hier sind einige der Ergebnisse:

Row | Time                    | Host                                  | Status | Path
--- | ----------------------- | ------------------------------------- | ------ | ------
 6  | 2020-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2020-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2020-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2020-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

BigQuery-Schema für weitergeleitete Logs

BigQuery-Tabellenschemas für weitergeleitete Logs basieren auf der Struktur des LogEntry-Typs und den Inhalten der Log-Nutzlasten. Cloud Logging wendet auch Regeln zum Kürzen der BigQuery-Schemafeldnamen für Audit-Logs und für bestimmte strukturierte Nutzlastfelder an. Sie können das Tabellenschema aufrufen, indem Sie in der BigQuery-Benutzeroberfläche eine Tabelle mit weitergeleiteten Logeinträgen auswählen.

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%% in jsonPayload.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 lautet jsonpayload_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

Tabellenorganisation

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. 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. Nachfolgende Logeinträge können zu einem Schemakonflikt führen. Für Informationen dazu, wann diese auftreten und wie sie behandelt werden, finden Sie unter Schemaabweichungen.

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

1: Die Zeitstempel der Logeinträge werden in UTC (koordinierte Weltzeit) ausgedrückt.

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 ist eine nach Datum fragmentierte Tabelle:

Eine Anleitung zum Erstellen von Senken finden Sie in den folgenden Ressourcen:

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 ein string ist, generiert dieser Logeintrag eine Tabelle mit einem Stringtyp für dieses Feld. Wenn Sie später jsonPayload.user_id als array loggen, führt dies zu einer Schemaabweichung.

  • Ein neuer Logeintrag enthält ein Feld, das nicht im aktuellen Schema enthalten ist. Wenn dieses Feld in die Zieltabelle eingefügt wird, wird das BigQuery-Spaltenlimit überschritten.

    Das neue Feld kann in der Zieltabelle verwendet werden, wenn dadurch das Spaltenlimit nicht überschritten wird.

Wenn BigQuery ein nicht übereinstimmendes Schema identifiziert, wird eine Tabelle im entsprechenden Dataset erstellt, um die Fehlerinformationen zu speichern. Die bestimmt den Tabellennamen. 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.

Fehlertabellenschema

Die Fehlertabelle enthält Daten aus dem LogEntry und Informationen zur Abweichung:

  • logEntry: Enthält den vollständigen Logeintrag. Der Logeintrag wird jedoch von JSON in einen String konvertiert.
  • schemaErrorDetail: Enthält die vollständige Fehlermeldung, die von BigQuery
  • sink: Enthält den vollständigen Ressourcenpfad für die Log-Senke.
  • logName: Aus dem LogEntry extrahiert.
  • timestamp: Extrahiert aus LogEntry.
  • receiveTimestamp: Extrahiert aus LogEntry.
  • severity: Extrahiert aus LogEntry.
  • insertId: Extrahiert aus LogEntry.
  • trace: Aus dem LogEntry extrahiert.
  • resourceType: Extrahiert aus LogEntry.

Logging kommuniziert dem Google 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.

Zukünftige Abweichungen beim Feldtyp vermeiden

Korrigieren Sie den Feldtyp so, dass er mit dem aktuellen Schema übereinstimmt. So korrigieren Sie Feldabweichungen für spätere Logeinträge. Informationen zu Informationen zur Korrektur eines Feldtyps Datentyp einer Spalte ändern

Manchmal kann der Feldtyp nicht geändert werden, z. B. nicht. Feldtyp für Logs, die automatisch von Google Cloud generiert werden Dienstleistungen. Um Schemaabweichungen zu vermeiden, wenn Sie einen Feldtyp nicht ändern können, die Tabelle umbenennen oder die Parameter der Senke ändern, sodass Logging erstellt die Tabelle in einem anderen Dataset neu. Für finden Sie unter Senken verwalten:

Fehlerbehebung

Wenn Logs im Ziel der Senke fehlen oder Sie anderweitig vermuten ob die Senke Logs nicht ordnungsgemäß weiterleitet, Fehlerbehebung bei Routinglogs

Preise

In Cloud Logging fallen keine Kosten für das Weiterleiten von Logs an einen unterstütztes Ziel; Am Ziel fallen jedoch möglicherweise Gebühren an. Mit Ausnahme des _Required-Log-Buckets fallen in Cloud Logging Kosten für das Streamen von Logs in Log-Buckets und für die Speicherung über die standardmäßige Aufbewahrungsdauer des Log-Buckets hinaus an.

Für das Kopieren von Logs, das Definieren von Log-Bereichen oder das Ausführen von Abfragen über die Seiten Log-Explorer oder Log Analytics fallen in Cloud Logging keine Gebühren an.

Weitere Informationen finden Sie in folgenden Dokumenten: