In Cloud Logging bezieht sich der Begriff strukturierte Logs auf Logeinträge, deren Nutzlasten mit dem Feld jsonPayload
strukturiert werden.
Wenn Sie die Cloud Logging API oder das gcloud
-Befehlszeilentool verwenden, können Sie die Struktur der Nutzlasten steuern. Beispiele finden Sie unter Strukturierte Logs schreiben.
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.
Spezielle Felder in JSON-Nutzlasten verwenden, um Logs mit dem Logging-Agent zu strukturieren
Sie können strukturierte Logs auf folgende Arten in Logging schreiben:
- Senden Sie die vollständige
LogEntry
-Struktur mitjsonPayload
an die Cloud Logging API. - Serialisierte JSON-Objekte dem Logging-Agent bereitstellen
Wenn Sie Google Kubernetes Engine oder die flexible App Engine-Umgebung verwenden, können Sie strukturierte Logs als JSON-Objekte schreiben, die in einer einzigen Zeile in stdout
oder stderr
serialisiert werden.
Der Logging-Agent sendet die strukturierten Logs dann als jsonPayload
der Struktur LogEntry
an Cloud Logging.
Einige Felder im JSON-Objekt werden vom Logging-Agent als speziell erkannt und in die Struktur LogEntry
extrahiert.
Diese speziellen JSON-Felder können verwendet werden, um die folgenden Felder in LogEntry
festzulegen:
severity
spanId
- Vom Nutzer definierte
labels
httpRequest
Da JSON präziser und vielseitiger ist als Textzeilen, können Sie JSON-Objekte verwenden, um mehrzeilige Nachrichten zu schreiben und Metadaten hinzuzufügen.
Wie Sie strukturierte Logeinträge für Ihre Anwendungen mit dem vereinfachten Format erstellen können, erfahren Sie in der folgenden Tabelle, in der die Felder und ihre Werte in JSON aufgeführt sind:
JSON-Logfeld |
LogEntry -Feld
|
Cloud Logging-Agent-Funktion | Beispielwert |
---|---|---|---|
severity
|
severity
|
Der Logging-Agent versucht, eine Vielzahl von bekannten Schweregradstrings zu finden, die die Liste der LogSeverity-Strings enthalten, die von der Logging API erkannt werden. | "severity":"ERROR"
|
message
|
textPayload (oder Teil von jsonPayload )
|
Die Nachricht, die in der Log-Eintragzeile im Loganzeige-Explorer angezeigt wird | "message":"There was an error in the application." Hinweis: message wird als textPayload gespeichert, wenn es das einzige Feld nach dem Der Logging-Agent entfernt die anderen Spezialfelder und
detect_json wurde nicht aktiviert. Andernfalls bleibt message
in jsonPayload . Wenn Ihr Logeintrag einen Ausnahme-Stacktrace enthält, sollte dieser im JSON-Logfeld message festgelegt werden, damit er geparst und in Error Reporting gespeichert werden kann. auf. |
log (nur Legacy-Google Kubernetes Engine) |
textPayload
|
Gilt nur für Legacy-Google Kubernetes Engine: Wenn nach dem Entfernen von Spezialfeldern nur ein Logfeld verbleibt, wird dieses Log als textPayload gespeichert. |
|
httpRequest
|
httpRequest
|
Ein strukturierter Datensatz im Format des Felds LogEntry
HttpRequest . |
"httpRequest":{"requestMethod":"GET"}
|
zeitbezogene Felder | timestamp
|
Weitere Informationen finden Sie unter Zeitbezogene Felder. | "times":"2020-10-12T07:20:50.52Z"
|
logging.googleapis.com/insertId
|
insertId
|
Weitere Informationen finden Sie unter insertId auf der Seite LogEntry . |
"logging.googleapis.com/insertId":"42"
|
logging.googleapis.com/labels
|
labels
|
Der Wert dieses Felds muss ein strukturierter Datensatz sein.
Weitere Informationen finden Sie unter labels auf der Seite LogEntry . |
"logging.googleapis.com/labels":
{"user_label_1":"value_1","user_label_2":"value_2"}
|
logging.googleapis.com/operation
|
operation
|
Der Wert dieses Felds wird auch im Log-Explorer verwendet, um zugehörige Logeinträge zu gruppieren.
Weitere Informationen finden Sie unter operation auf der Seite LogEntry . |
"logging.googleapis.com/operation":
{"id":"get_data","producer":"github.com/MyProject/MyApplication",
"first":"true"}
|
logging.googleapis.com/sourceLocation
|
sourceLocation
|
Standortinformationen des Quellcodes, die gegebenenfalls mit dem Logeintrag verknüpft sind.
Weitere Informationen finden Sie unter LogEntrySourceLocation auf der Seite LogEntry . |
"logging.googleapis.com/sourceLocation":
{"file":"get_data.py","line":"142","function":"getData"}
|
logging.googleapis.com/spanId
|
spanId
|
Die Span-ID im Trace, der dem Logeintrag zugeordnet ist.
Weitere Informationen finden Sie unter spanId auf der Seite LogEntry . |
"logging.googleapis.com/spanId":"000000000000004a
|
logging.googleapis.com/trace
|
trace
|
Ressourcenname des Trace, der, falls vorhanden, mit dem Logeintrag verknüpft ist.
Weitere Informationen finden Sie unter trace auf der Seite LogEntry .
|
"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Hinweis: Wenn nicht in stdout oder stderr geschrieben wird, sollte der Wert dieses Felds Sie können das Format als projects/[PROJECT-ID]/traces/[TRACE-ID] haben, damit es von der Loganzeige und dem Trace Viewer verwendet werden kann, um Logeinträge zu gruppieren und sie im Einklang mit Traces anzuzeigen.
Wenn autoformat_stackdriver_trace "true" ist und [V] mit dem Format von ResourceTrace
traceId übereinstimmt, hat das Feld LogEntry trace den Wert .
projects/[PROJECT-ID]/traces/[V] verwendet. |
logging.googleapis.com/trace_sampled
|
traceSampled
|
Der Wert dieses Felds muss entweder true oder false sein.
Weitere Informationen finden Sie unter traceSampled auf der Seite LogEntry . |
logging.googleapis.com/trace_sampled":"false"
|
Erstellen Sie zur Erstellung von Logeinträgen im vereinfachten Format eine JSON-Darstellung des Eintrags mithilfe der Felder. 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" }
Das folgende Beispiel zeigt den resultierenden Logeintrag:
{ "insertId": "42", "jsonPayload": { "message": "There was an error in the application", "times": "2019-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
Der Logging-Agent google-fluentd
ist eine Cloud Logging-spezifische Paketversion des Fluentd-Logdaten-Collectors.
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/
, wo nun auch der Standardparser standardmäßig aktiviert sein sollte.
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 Aufrufen von Logeinträgen im Log-Explorer der Cloud Console finden Sie unter Log-Explorer verwenden.
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.