Strukturiertes Logging

In Cloud Logging bezieht sich der Begriff strukturierte Logs auf Logeinträge, deren Nutzlasten mit dem Feld jsonPayload strukturiert werden. Mit der Cloud Logging API oder mit dem gcloud-Befehlszeilentool lässt sich die Struktur der Nutzlasten entsprechend steuern. Wenn Sie Logeinträge mit dem Cloud Logging-Agent abrufen, können Sie festlegen, dass der Logging-Agent die Nutzlasten in das JSON-Format konvertiert.

Wenn Sie den BindPlane-Dienst zum Aufnehmen von Logs nutzen, 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 BindPlane-Dokumentation unter Logdaten finden.

Weitere Informationen zu den verschiedenen Nutzlastformaten finden Sie unter LogEntry.

Hier sehen Sie ein Beispiel für einen Protokolleintrag, in dem die strukturierte Nutzlast fett hervorgehoben ist:

{
 insertId:  "1m9mtk4g3mwilhp"
 jsonPayload: {
  "code": "structured-log-code"
  "message": "This is a log from the log file at test-structured-log.log"
 }
 labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
 }
 logName:  "projects/my-sample-project-12345/logs/structured-log"
 receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
 resource: {
  labels: {
   instance_id:  "5351724540900470204"
   project_id:  "my-sample-project-12345"
   zone:  "us-central1-c"
  }
  type:  "gce_instance"
 }
 timestamp:  "2018-03-21T01:53:39.071920609Z"
}

Betrieb

Der Logging-Agent google-fluentd ist eine modifizierte Version 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.

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.

Standardmäßig aktivierte Standardparser

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

Parsername	Konfigurationsdatei
syslog	/etc/google-fluentd/config.d/syslog.conf
nginx	/etc/google-fluentd/config.d/nginx.conf
apache2	/etc/google-fluentd/config.d/apache.conf
apache_error	/etc/google-fluentd/config.d/apache.conf

Hinweise zum Aktivieren des strukturierten Loggings während der Installation des Logging-Agents finden Sie im Abschnitt Installation.

Installation

Zum Aktivieren des strukturierten Loggings müssen Sie die Standardkonfiguration des Logging-Agents bei der Installation oder Neuinstallation ändern. Durch Aktivieren des strukturierten Loggings werden die zuvor aufgelisteten Konfigurationsdateien ersetzt. Die Anwendungsweise des Agents selbst wird 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 aus Cloud Logging exportiert werden, kann sich die Änderung auf alle Post-Processing-Anwendungen auswirken. Bei BigQuery-Exporten weist BigQuery die neuen Logeinträge für den Rest des Tages zurück, da sie das falsche Schema haben.

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

Die Konfigurationsdateien des Logging-Agents finden Sie unter /etc/google-fluentd/config.d/. Dort sollte dann auch der Standardparser standardmäßig aktiviert sein.

Apache-Zugriffslogformat konfigurieren

Der 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 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 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.

Nginx-Zugriffslogformat konfigurieren

Der 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 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 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 3 Codebeispiele zeigen eine Logzeile im Logdatensatz, eine Konfiguration mit einem regulären Ausdruck, der das Format der Logzeile angibt, und den aufgenommenen 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:  "2018-03-21T01:47:11.475065313Z"
    resource: {
      labels: {
        instance_id:  "3914079432219560274"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
    }
    timestamp:  "2018-03-21T01:47:05.051902169Z"
   }
  

Strukturierte Logs ansehen

Informationen zum Suchen in Logs und zum Abruf von Logeinträgen in der Loganzeige der Cloud Console finden Sie unter Logs ansehen.

Informationen zum Lesen von Logeinträgen mit dem gcloud-Befehlszeilentool oder der API finden Sie unter Logeinträge lesen.

Fehlerbehebung

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