Strukturiertes Logging

In diesem Dokument wird das Konzept des strukturierten Loggings und die Methoden zum Strukturieren von Nutzlastfeldern von Logeinträgen erläutert. Wenn die Lognutzlast als JSON-Objekt formatiert und dieses Objekt im Feld jsonPayload gespeichert wird, wird der Logeintrag als strukturierter Logeintrag bezeichnet. Für diese Protokolle können Sie Abfragen erstellen, die nach bestimmten JSON-Pfaden suchen, und bestimmte Felder in der Protokollnutzlast indexieren. Wenn die Lognutzlast dagegen als String formatiert und im Feld textPayload gespeichert wird, ist der Logeintrag unstrukturiert. Sie können im Textfeld zwar suchen, aber den Inhalt nicht indexieren.

So erstellen Sie strukturierte Logeinträge:

• Rufen Sie die API-Methode entries.write auf und geben Sie einen vollständig formatierten LogEntry an.
• Führen Sie den Befehl gcloud logging write aus.

• Verwenden Sie eine Cloud Logging-Clientbibliothek, die strukturierte Protokolle schreibt.

• BindPlane-Dienst verwenden

• Agent zum Schreiben von Protokollen verwenden:

  • Einige Google Cloud-Dienste enthalten einen integrierten Logging-Agenten, der die Daten, die in stdout oder stderr geschrieben werden, als Protokolle an Cloud Logging sendet. Sie können diesen Ansatz für Google Cloud-Dienste wie die Google Kubernetes Engine, die flexible App Engine-Umgebung und Cloud Run-Funktionen verwenden.

  • Für Compute Engine-VMs können Sie den Ops-Agent oder den bisherigen Logging-Agent installieren und konfigurieren und dann mit dem installierten Agenten Logs an Cloud Logging senden.

Weitere Informationen zu diesen Ansätzen finden Sie in den folgenden Abschnitten.

Protokolle mit Clientbibliotheken oder der API schreiben

Sie können Protokolldaten mithilfe der Cloud Logging-Clientbibliotheken schreiben, die die Cloud Logging API aufrufen. Sie können die Cloud Logging API auch direkt aufrufen. Clientbibliotheken können die Ausfüllung der speziellen JSON-Felder vereinfachen, indem einige Informationen automatisch erfasst und Schnittstellen bereitgestellt werden, um die Felder entsprechend auszufüllen. Wenn Sie jedoch die Struktur Ihrer Nutzlasten vollständig steuern möchten, rufen Sie die Cloud Logging API direkt auf und übergeben Sie die vollständige LogEntry-Struktur an die Cloud Logging API.

Weitere Informationen finden Sie in der Referenz zu entries.write.

Codebeispiele finden Sie unter Strukturierte Protokolle schreiben.

Protokolle mit der gcloud CLI schreiben

Sie können Protokolldaten mit der gcloud CLI schreiben. Die Benutzeroberfläche unterstützt unstrukturierte und strukturierte Protokolle. Wenn Sie ein strukturiertes Protokoll schreiben möchten, geben Sie dem Befehl ein serialisiertes JSON-Objekt an.

Eine Kurzanleitung finden Sie unter Logeinträge mit der Google Cloud CLI schreiben und abfragen.

Codebeispiele finden Sie in der gcloud logging write-Referenz.

Protokolle mit BindPlane schreiben

Sie können den BindPlane-Dienst verwenden, um Logs an Logging zu senden. Bei diesen Logs haben die Nutzlasten das JSON-Format und sind gemäß dem Quellsystem strukturiert. Informationen zum Suchen und Aufrufen von Logs, die über BindPlane aufgenommen wurden, finden Sie in der Kurzanleitung zu BindPlane.

Protokolle mit einem Agenten schreiben

Sie können den Ops-Agent oder den alten Cloud Logging-Agent verwenden, um Logs aus Ihren Compute Engine-Instanzen abzurufen. Beide Agents können Messwerte aus Drittanbieteranwendungen erfassen und unterstützen strukturiertes Logging:

• Der Ops-Agent ist der empfohlene Agent zum Erfassen von Telemetriedaten aus Ihren Compute Engine-Instanzen. Dieser Agent kombiniert Logging und Messwerte in einem einzigen Agent, bietet eine YAML-basierte Konfiguration und unterstützt Logging mit hohem Durchsatz.

  Informationen zum Konfigurieren des Ops-Agents für die Unterstützung strukturierter Protokolle oder zum Anpassen der Form eines strukturierten Logs finden Sie unter Ops-Agent konfigurieren.

• Der alte Cloud Logging-Agent sammelt Protokolle. Dieser Agent erhebt keine anderen Formen der Telemetrie.

Der Rest dieses Abschnitts bezieht sich auf den bisherigen Logging-Agent.

Logging-Agent: spezielle JSON-Felder

Einige Felder im JSON-Objekt werden vom bisherigen Logging-Agent als spezielle Felder erkannt und in die Struktur LogEntry extrahiert. Mit diesen speziellen JSON-Feldern können die folgenden Felder in LogEntry festgelegt werden:

• severity
• spanId
• labels (vom Nutzer definiert)
• httpRequest

Da JSON genauer und vielseitiger als Textzeilen ist, können Sie JSON-Objekte verwenden, um mehrzeilige Nachrichten zu schreiben und Metadaten hinzuzufügen.

In der folgenden Tabelle sind die Felder und ihre Werte im JSON-Format aufgeführt, um strukturierte Logeinträge für Ihre Anwendungen mit dem vereinfachten Format zu erstellen:

Wenn Sie Logeinträge im vereinfachten Format erstellen möchten, erstellen Sie eine JSON-Darstellung des Eintrags mit den Feldern. Alle Felder sind optional.

Im Folgenden finden Sie ein Beispiel für einen vereinfachten JSON-Logeintrag:

{
  "severity":"ERROR",
  "message":"There was an error in the application.",
  "httpRequest":{
    "requestMethod":"GET"
  },
  "times":"2020-10-12T07:20:50.52Z",
  "logging.googleapis.com/insertId":"42",
  "logging.googleapis.com/labels":{
    "user_label_1":"value_1",
    "user_label_2":"value_2"
  },
  "logging.googleapis.com/operation":{
    "id":"get_data",
    "producer":"github.com/MyProject/MyApplication",
    "first":"true"
  },
  "logging.googleapis.com/sourceLocation":{
    "file":"get_data.py",
    "line":"142",
    "function":"getData"
  },
  "logging.googleapis.com/spanId":"000000000000004a",
  "logging.googleapis.com/trace":"projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "logging.googleapis.com/trace_sampled":false
}

Dies ist ein Beispiel für den resultierenden Logeintrag:

{
  "insertId": "42",
  "jsonPayload": {
    "message": "There was an error in the application",
    "times": "2020-10-12T07:20:50.52Z"
  },
  "httpRequest": {
    "requestMethod": "GET"
  },
  "resource": {
    "type": "k8s_container",
    "labels": {
      "container_name": "hello-app",
      "pod_name": "helloworld-gke-6cfd6f4599-9wff8",
      "project_id": "stackdriver-sandbox-92334288",
      "namespace_name": "default",
      "location": "us-west4",
      "cluster_name": "helloworld-gke"
    }
  },
  "timestamp": "2020-11-07T15:57:35.945508391Z",
  "severity": "ERROR",
  "labels": {
    "user_label_2": "value_2",
    "user_label_1": "value_1"
  },
  "logName": "projects/stackdriver-sandbox-92334288/logs/stdout",
  "operation": {
    "id": "get_data",
    "producer": "github.com/MyProject/MyApplication",
    "first": true
  },
  "trace": "projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "sourceLocation": {
    "file": "get_data.py",
    "line": "142",
    "function": "getData"
  },
  "receiveTimestamp": "2020-11-07T15:57:42.411414059Z",
  "spanId": "000000000000004a"
}

Logging-Agent: Konfiguration

Der bisherige Logging-Agent google-fluentd ist eine Cloud Logging-spezifische Paketversion des Logdaten-Collectors Fluentd. Der Logging-Agent verwendet die Fluentd-Standardkonfiguration und die Eingabe-Plugins von Fluentd, um Ereignislogs aus externen Quellen wie Dateien auf der Festplatte abzurufen oder um eingehende Logdatensätze zu analysieren.

Für Fluentd gibt es verschiedene unterstützte Parser, die Logs extrahieren und in strukturierte (JSON-)Nutzlasten konvertieren.

Wenn Sie eine Logquelle mit format [PARSER_NAME] konfigurieren, können Sie die integrierten Parser von Fluentd nutzen. Informationen zum Konfigurieren des bisherigen Logging-Agents finden Sie unter Logging-Agent konfigurieren.

Die folgenden Codebeispiele zeigen die Fluentd-Konfiguration, den Eingangslogdatensatz und die Ausgabe der strukturierten Nutzlast, die Teil eines Cloud Logging-Logeintrags ist:

• Fluentd-Konfiguration:

    <source>
      @type tail
  
      format syslog # This uses a predefined log format regex named
                    # `syslog`. See details at https://docs.fluentd.org/parser/syslog.
  
      path /var/log/syslog
      pos_file /var/lib/google-fluentd/pos/syslog.pos
      read_from_head true
      tag syslog
    </source>
  

• Logdatensatz (Eingabe):

    <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test
  

• Strukturierte Nutzlast (Ausgabe):

    jsonPayload: {
        "pri": "6",
        "host": "192.168.0.1",
        "ident": "fluentd",
        "pid": "11111",
        "message": "[error] Syslog test"
    }
  

Weitere Informationen zur Funktionsweise des Parsers syslog finden Sie in der ausführlichen Dokumentation zu Fluentd.

Logging-Agent: Standardparser standardmäßig aktiviert

Die folgende Tabelle enthält die Standardparser, die im Agent enthalten sind, wenn Sie das strukturierte Logging aktivieren:

Eine Anleitung zum Aktivieren des strukturierten Loggings bei der Installation des bisherigen Logging-Agent finden Sie im Abschnitt Installation.

Logging-Agent: Installation

Wenn Sie das strukturierte Logging aktivieren möchten, müssen Sie die Standardkonfiguration des bisherigen Logging-Agent bei der Installation oder Neuinstallation ändern. Durch Aktivieren des strukturierten Loggings werden die zuvor aufgelisteten Konfigurationsdateien ersetzt. Der Vorgang des Agents selbst wird jedoch nicht geändert.

Wenn Sie das strukturierte Logging aktivieren, werden die aufgelisteten Logs in Logeinträge mit anderen Formaten als vor der Aktivierung strukturierter Logs umgewandelt. Wenn die Logs an Ziele außerhalb von Logging weitergeleitet werden, kann sich die Änderung auf alle Post-Processing-Anwendungen auswirken. Wenn Sie beispielsweise Logs an BigQuery weiterleiten, weist BigQuery die neuen Logeinträge für den Rest des Tages zurück, da sie ein falsches Schema haben.

Eine Anleitung zur Installation des alten Logging-Agent und zur Aktivierung des strukturierten Loggings finden Sie unter Agent installieren.

Die Konfigurationsdateien des bisherigen Logging-Agent finden Sie unter /etc/google-fluentd/config.d/. Diese Dateien sollten nun die standardmäßig aktivierten Parser enthalten.

Logging-Agent: Apache-Zugriffslogformat konfigurieren

Der alte Logging-Agent speichert Apache-Zugriffslogdaten standardmäßig im Feld jsonPayload. Beispiel:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

Alternativ können Sie den bisherigen Logging-Agent so konfigurieren, dass bestimmte Felder in das Feld httpRequest extrahiert werden. Beispiel:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

Die Konfiguration des Felds httpRequest, wie im vorstehenden Beispiel dargestellt, unterstützt Tracing, das heißt, die Google Cloud Console zeigt alle Logs für eine bestimmte HTTP-Anfrage in einer Hierarchie an.

Fügen Sie zum Konfigurieren dieser Extraktion am Ende von /etc/google-fluentd/config.d/apache.conf Folgendes hinzu:

<filter apache-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
    "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, host, referer
</filter>

Weitere Informationen zum Konfigurieren von Logeinträgen finden Sie unter Logeinträge ändern.

Logging-Agent: Nginx-Zugriffslogformat konfigurieren

Der alte Logging-Agent speichert nginx-Zugriffslogdaten standardmäßig im Feld jsonPayload. Beispiel:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "remote":"127.0.0.1",
    "host":"192.168.0.1",
    "user":"some-user",
    "method":"GET",
    "path":"/some-path",
    "code":"200",
    "size":"777",
    "referrer":"some-referrer",
    "agent":"Opera/12.0",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

Alternativ können Sie den bisherigen Logging-Agent so konfigurieren, dass bestimmte Felder in das Feld httpRequest extrahiert werden. Beispiel:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "remoteIp": "127.0.0.1",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

Die Konfiguration des Felds httpRequest, wie im vorstehenden Beispiel dargestellt, unterstützt Tracing, das heißt, die Google Cloud Console zeigt alle Logs für eine bestimmte HTTP-Anfrage in einer Hierarchie an.

Fügen Sie zum Konfigurieren dieser Extraktion am Ende von /etc/google-fluentd/config.d/nginx.conf Folgendes hinzu:

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

Weitere Informationen zum Konfigurieren von Logeinträgen finden Sie unter Logeinträge ändern.

Eigenen Parser schreiben

Wenn Ihre Logs von Standardparsern nicht unterstützt werden, können Sie eigene schreiben. Parser bestehen aus einem regulären Ausdruck, mit dem Logdatensätze abgeglichen und Labels auf die Teile angewendet werden.

Die folgenden Codebeispiele zeigen eine Logzeile im Logdatensatz, eine Konfiguration mit einem regulären Ausdruck, der das Format der Logzeile angibt, und den gespeicherten Protokolleintrag:

• Eine Logzeile im Logdatensatz:

  REPAIR CAR $500
  

• Eine Konfiguration mit einem regulären Ausdruck, der das Format der Logzeile angibt:

  $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
  $ cat /etc/google-fluentd/config.d/test-structured-log.conf
  <source>
    @type tail
  
    # Format indicates the log should be translated from text to
    # structured (JSON) with three fields, "action", "thing" and "cost",
    # using the following regex:
    format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
    # The path of the log file.
    path /tmp/test-structured-log.log
    # The path of the position file that records where in the log file
    # we have processed already. This is useful when the agent
    # restarts.
    pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag structured-log
  </source>
  

• Der resultierende Protokolleintrag:

  {
  insertId:  "eps2n7g1hq99qp"
  jsonPayload: {
    "action": "REPAIR"
    "thing": "CAR"
    "cost": "500"
  }
  labels: {
    compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/structured-log"
  receiveTimestamp:  "2023-03-21T01:47:11.475065313Z"
  resource: {
    labels: {
      instance_id:  "3914079432219560274"
      project_id:  "my-sample-project-12345"
      zone:  "us-central1-c"
    }
    type:  "gce_instance"
  }
  timestamp:  "2023-03-21T01:47:05.051902169Z"
  }
  

Probleme beheben

Informationen zur Behebung häufig auftretender Probleme bei der Installation oder der Interaktion mit dem bisherigen Logging-Agent finden Sie unter Fehlerbehebung beim Agent.

Nächste Schritte

• Informationen zum Abfragen und Ansehen von Logeinträgen finden Sie unter Logs mit dem Log-Explorer ansehen.

• Informationen zum Lesen von Logeinträgen mithilfe der Google Cloud CLI finden Sie unter Logeinträge lesen.

• Informationen zum Lesen von Logeinträgen über die Logging API finden Sie unter der Methode entries.list.