Logging-Agent konfigurieren

Diese Seite enthält Informationen zu den standardmäßigen und benutzerdefinierten Konfigurationen des Cloud Logging-Agents.

Die meisten Nutzer brauchen diese Seite nicht zu lesen. Lesen Sie diese Seite, wenn Folgendes zutrifft:

• Sie interessieren sich für genauere technische Details zur Konfiguration des Cloud Logging-Agenten.

• Sie möchten die Konfiguration des Cloud Logging-Agenten ändern.

Standardkonfiguration

Der Logging-Agent google-fluentd ist eine modifizierte Version des Logdaten-Collectors fluentd. Der Logging-Agent wird mit einer Standardkonfiguration ausgeliefert. In den meisten Fällen ist keine zusätzliche Konfiguration erforderlich.

In der Standardkonfiguration streamt der Stackdriver Logging-Agent Logs aus der Liste der Standardlogs zu Cloud Logging. Sie können den Agent so konfigurieren, dass zusätzliche Logs gestreamt werden. Weitere Informationen erhalten Sie unter Logging-Agent-Konfiguration anpassen auf dieser Seite.

Der Logging-Agent verwendet fluentd-Eingabe-Plug-ins, um Ereignisprotokolle aus externen Quellen wie Dateien auf der Festplatte abzurufen oder eingehende Logdatensätze zu analysieren. Eingabe-Plug-ins sind mit dem Agent gebündelt oder können separat als Ruby Gems installiert werden (siehe die Liste der gebündelten Plug-ins).

Der Agent liest in Logdateien gespeicherte Logdatensätze auf der VM-Instanz über das in fluentd integrierte Plug-in in_tail. Jeder Logdatensatz wird in eine Logeintragsstruktur für Cloud Logging konvertiert. Der Inhalt jedes Logdatensatzes wird meist in den Nutzdaten der Logeinträge aufgezeichnet. Logeinträge enthalten aber auch Standardelemente wie einen Zeitstempel und den Schweregrad. Der Logging-Agent erfordert, dass jeder Logdatensatz mit einem Tag im Stringformat versehen wird. Alle Abfragen und Ausgabe-Plug-ins entsprechen einer bestimmten Gruppe von Tags. Der Logname folgt normalerweise dem Format projects/[PROJECT-ID]/logs/[TAG]. Dieser Logname enthält beispielsweise das Tag structured-log:

projects/my-sample-project-12345/logs/structured-log

Das Ausgabe-Plug-in wandelt jede intern strukturierte Nachricht in einen Logeintrag in Cloud Logging um. Die Nutzlast wird zu Text oder zur JSON-Nutzlast.

Die folgenden Abschnitte auf dieser Seite beschreiben die Standardkonfiguration im Detail.

Definitionen für die Standardkonfiguration

In den folgenden Abschnitten werden die Definitionen der Standardkonfiguration für syslog und das Plug-in zur Weiterleitung der Eingabe, der Eingabekonfigurationen für Anwendungslogs von Drittanbietern (z. B. aus der Liste der Standardlogs) und der Konfiguration des Ausgabe-Plug-ins fluentd von Google Cloud beschrieben.

Speicherort der Stamm-Konfigurationsdatei

• Linux: /etc/google-fluentd/google-fluentd.conf

  Diese Root-Konfigurationsdatei importiert auch alle Konfigurationsdateien aus dem Ordner /etc/google-fluentd/config.d.

• Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

  Wenn Sie einen Logging-Agent vor v1-5 ausführen, lautet der Speicherort: C:\GoogleStackdriverLoggingAgent\fluent.conf

Syslog-Konfiguration

Hinweis: Die folgende syslog-Standardkonfiguration gehört zum Paket google-fluentd-catch-all-config und ist ausschließlich für Linux-Betriebssysteme verfügbar.

• Speicherorte der Konfigurationsdateien: /etc/google-fluentd/config.d/syslog.conf

• Beschreibung: Diese Datei enthält die Konfiguration zur Angabe von syslog als Logeingabe.

• Siehe das Konfigurations-Repository.

Konfigurationsname	Typ	Standard	Beschreibung
format	String	/^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/	Das Format von Syslogs.
path	String	/var/log/syslog	Der Pfad der Syslog-Datei.
pos_file	String	/var/lib/google-fluentd/pos/syslog.pos	Der Pfad der Positionsdatei für diese Logeingabe. fluentd protokolliert die zuletzt gelesene Position in dieser Datei. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
read_from_head	bool	true	Ob man beginnt, die Logs vom Dateianfang anstatt vom Dateiende zu lesen. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
tag	String	syslog	Das Logtag für diese Logeingabe.

in_forward-Eingabe-Plug-in-Konfiguration

Hinweis: Die folgende standardmäßige Plug-in-Konfiguration in_forward gehört zum Paket google-fluentd-catch-all-config und ist nur für Linux-Betriebssysteme verfügbar.

• Speicherorte der Konfigurationsdateien: /etc/google-fluentd/config.d/forward.conf

• Beschreibung: Diese Datei enthält die Konfiguration für das Eingabe-Plug-in in_forward fluentd. Mit dem Eingabe-Plug-in in_forward können Sie Logs über einen TCP-Socket übergeben.

• Weitere Informationen zu diesem Plug-in und dem Konfigurations-Repository finden Sie in der Dokumentation zu fluentd.

Konfigurationsname	Typ	Standard	Beschreibung
port	int	24224	Der zu überwachende Port.
bind	String	127.0.0.1	Die zu überwachende Bindeadresse. Standardmäßig werden nur Verbindungen von localhost akzeptiert. Diese Konfiguration muss in 0.0.0.0 geändert werden, um auch andere zu akzeptieren.

Eingabekonfiguration von Drittanbieteranwendungs-Logs

Hinweis: Die folgende standardmäßige Anwendungslog-Konfiguration gehört zum Paket google-fluentd-catch-all-config und ist nur für Linux-Betriebssysteme verfügbar.

• Speicherorte der Konfigurationsdateien: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

• Beschreibung: Dieses Verzeichnis enthält Konfigurationsdateien für die Angabe von Logdateien von Drittanbieteranwendungen als Logeingaben. Jede Datei, außer syslog.conf und forward.conf, stellt eine Anwendung dar (z. B. apache.conf für die Apache-Anwendung).

• Siehe das Konfigurations-Repository.

Konfigurationsname	Typ	Standard	Beschreibung
format^1	String	Variiert je nach Anwendung	Das Format des Logs. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
path	String	Variiert je nach Anwendung	Der Pfad der Log-Datei(en). Mehrere Pfade können getrennt durch ‘,’ angegeben werden. * und das strftime-Format kann hinzugefügt werden, um die Watch-Datei dynamisch einzuschließen/zu entfernen. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
pos_file	String	Variiert je nach Anwendung	Der Pfad der Positionsdatei für diese Logeingabe. fluentd protokolliert die zuletzt gelesene Position in dieser Datei. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
read_from_head	bool	true	Ob man beginnt, die Logs vom Dateianfang anstatt vom Dateiende zu lesen. Sehen Sie sich die ausführliche fluentd-Dokumentation an.
tag	String	Variiert; der Name der Anwendung	Das Logtag für diese Logeingabe.

¹ Wenn Sie die <parse>-Stanza nutzen, geben Sie das Format des Logs über @type an.

Google Cloud fluentd-Ausgabe-Plug-in-Konfiguration

• Speicherorte der Konfigurationsdateien:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Wenn Sie einen Logging-Agent vor v1-5 ausführen, lautet der Speicherort: C:\GoogleStackdriverLoggingAgent\fluent.conf

• Beschreibung: Diese Datei enthält Konfigurationsoptionen zur Steuerung des Verhaltens des Ausgabe-Plug-ins fluentd von Google Cloud.

• Rufen Sie das Konfigurations-Repository auf.

Konfigurationsname	Typ	Standard	Beschreibung
buffer_chunk_limit	String	512KB	Wenn Logdatensätze eintreffen, werden diejenigen, die nicht schnell genug in nachgelagerte Komponenten geschrieben werden können, in eine Warteschlange von Blöcken geschoben. Diese Konfiguration legt die Größenbeschränkung für jeden Block fest. Standardmäßig wird die Blockgröße konservativ festgelegt, um zu vermeiden, dass die empfohlene Blockgröße von 5 MB pro Schreibanfrage in der Logging-API überschritten wird. Logeinträge in der API-Anfrage können 5 bis 8 Mal größer sein als die ursprüngliche Loggröße mit allen angehängten zusätzlichen Metadaten. Ein Pufferblock wird gelöscht, wenn eine der beiden folgenden Bedingungen erfüllt ist: 1. flush_interval tritt ein. 2. Die Puffergröße erreicht buffer_chunk_limit.
flush_interval	String	5s	Wenn Logdatensätze eintreffen, werden diejenigen, die nicht schnell genug in nachgelagerte Komponenten geschrieben werden können, in eine Warteschlange von Blöcken geschoben. Die Konfiguration legt fest, wie lange vorher ein Blockpuffer geleert werden muss. Ein Pufferblock wird gelöscht, wenn eine der beiden folgenden Bedingungen erfüllt ist: 1. flush_interval tritt ein. 2. Die Puffergröße erreicht buffer_chunk_limit.
disable_retry_limit	bool	false	Erzwingt eine Beschränkung der Anzahl an Wiederholungen fehlgeschlagener Löschvorgänge des Pufferblocks. Detaillierte Spezifikationen finden Sie in retry_limit, retry_wait und max_retry_wait.
retry_limit	int	3	Wenn ein Pufferblock nicht gelöscht werden kann, wird fluentd es standardmäßig später noch einmal versuchen. Diese Konfiguration legt fest, wie viele Wiederholungsversuche durchgeführt werden müssen, bevor ein problematischer Pufferblock gelöscht wird.
retry_wait	int	10s	Wenn ein Pufferblock nicht gelöscht werden kann, wird fluentd es standardmäßig später noch einmal versuchen. Diese Konfiguration legt das Warteintervall in Sekunden vor dem ersten Wiederholungsversuch fest. Das Warteintervall wird bei jedem darauffolgenden Versuch (20s, 40s, ...) verdoppelt, bis entweder retry_ limit oder max_retry_wait erreicht ist.
max_retry_wait	int	300	Wenn ein Pufferblock nicht gelöscht werden kann, wird fluentd es standardmäßig später noch einmal versuchen. Das Warteintervall wird bei jedem darauffolgenden Versuch (20s, 40s, ...) verdoppelt. Diese Konfiguration legt das Maximum an Warteintervallen in Sekunden fest. Wenn das Warteintervall dieses Limit erreicht, stoppt die Verdopplung.
num_threads	int	8	Die Anzahl gleichzeitiger Löschvorgänge für Logs, die vom Ausgabe-Plug-in verarbeitet werden können.
use_grpc	bool	true	Gibt an, ob gRPC anstelle von REST/JSON für die Kommunikation mit der Logging API verwendet werden soll. Bei aktiviertem gRPC-Framework ist die CPU-Auslastung in der Regel geringer.
grpc_compression_algorithm	enum	none	Bestimmt bei der Nutzung von gRPC, welches Komprimierungsschema verwendet wird. Kann none oder gzip sein.
partial_success	bool	true	Gibt an, ob der Teilerfolg für die Logaufnahme unterstützt werden soll. Wenn true, werden ungültige Logeinträge in einem vollständigen Satz gelöscht und gültige Logeinträge erfolgreich in die Logging API aufgenommen. Wenn false, wird der gesamte Satz gelöscht, wenn er ungültige Logeinträge enthält.
enable_monitoring	bool	true	Wenn true festgelegt ist, exportiert der Logging-Agent interne Telemetriedaten. Weitere Informationen finden Sie unter Ausgabe des Plug-ins „Telemetrie“.
monitoring_type	String	opencensus	Die Art der Überwachung. Die unterstützten Optionen sind opencensus und prometheus. Weitere Informationen finden Sie unter Ausgabe des Plug-ins „Telemetrie“.
autoformat_stackdriver_trace	bool	true	Bei Einstellung auf true wird der Trace neu formatiert, wenn der Wert im Feld logging.googleapis.com/trace der strukturierten Nutzlast dem traceId-Format von ResourceTrace entspricht. Details zur automatischen Formatierung finden Sie unter Spezielle Felder in strukturierten Nutzlasten.

Monitoring-Konfiguration

Ausgabe-Plug-in-Telemetrie

Die Seiteenable_monitoring legen Sie fest, ob die Google Cloudfluentd Ausgabe-Plug-in seine interne Telemetrie erfasst. Wenn true festgelegt ist, verfolgt der Logging-Agent die Anzahl der Logeinträge, die an Cloud Logging gesendet werden sollen, sowie die tatsächliche Anzahl der Logeinträge, die erfolgreich von Cloud Logging aufgenommen wurden. Wenn false festgelegt ist, werden vom Ausgabe-Plug-in keine Messwerte erfasst.

Die Option monitoring_type legt fest, wie diese Telemetrie vom Agent verfügbar gemacht wird. Im Folgenden finden Sie eine Liste der Messwerte.

Wenn prometheus festgelegt ist, macht der Logging-Agent Messwerte auf dem Prometheus-Endpunkt (localhost:24231/metrics) standardmäßig verfügbar (siehe prometheus- und prometheus_monitor-Plug-in-Konfiguration für Details wie Sie dies anpassen können). Damit auf Compute Engine-VMs diese Messwerte in die Monitoring API geschrieben werden können, muss der Monitoring-Agent ebenfalls installiert sein und ausgeführt werden.

Wenn dieser Wert auf opencensus gesetzt ist (Standardeinstellung seit v1.6.25), schreibt der Logging-Agent seine eigenen Zustandsmesswerte direkt in die Monitoring API. Dies erfordert, dass dem Compute Engine-Standarddienstkonto die Rolle roles/monitoring.metricWriter zugewiesen wird, auch wenn der Monitoring-Agent nicht installiert ist.

Die folgenden Messwerte werden sowohl vom Monitoring-Agent als auch vom Logging-Agent im opencensus-Modus in die Monitoring API geschrieben:

• agent.googleapis.com/agent/uptime mit dem Label version: Verfügbarkeit des Logging-Agents.
• agent.googleapis.com/agent/log_entry_count mit dem Label response_code: Anzahl der vom Logging-Agent geschriebenen Logeinträge.
• agent.googleapis.com/agent/log_entry_retry_count mit dem Label response_code: Anzahl der vom Logging-Agent geschriebenen Logeinträge.
• agent.googleapis.com/agent/request_count mit dem Label response_code: Anzahl der API-Anfragen vom Logging-Agent.

Diese Messwerte werden auf der Seite Agent-Messwerte ausführlicher beschrieben.

Darüber hinaus werden die folgenden Prometheus-Messwerte vom Ausgabe-Plug-in im prometheus-Modus zur Verfügung gestellt:

• uptime mit dem Label version: Verfügbarkeit des Logging-Agents.
• stackdriver_successful_requests_count mit den Labels grpc und code: Die Anzahl der erfolgreichen Anfragen an die Logging API.
• stackdriver_failed_requests_count mit den Labels grpc und code: Die Anzahl der fehlgeschlagenen Anfragen an die Logging API, aufgeschlüsselt nach Fehlercode.
• stackdriver_ingested_entries_count mit den Labels grpc und code: Die Anzahl der Logeinträge, die von der Logging API aufgenommen wurden.
• stackdriver_dropped_entries_count mit den Labels grpc und code: Die Anzahl der von der Logging API abgelehnten Logeinträge.
• stackdriver_retried_entries_count mit grpc und code labels: Die Anzahl der Logeinträge, die vom Google Cloud-Ausgabe-Plug-in fluentd aufgrund eines vorübergehenden Fehlers nicht aufgenommen werden konnten und für die dies wiederholt wurde.

Konfiguration Plug-in "prometheus" und "prometheus_monitor"

Hinweis: Die folgende standardmäßige Monitoringkonfiguration ist nur für Linux-Betriebssysteme verfügbar.

• Speicherorte der Konfigurationsdateien: /etc/google-fluentd/google-fluentd.conf

• Beschreibung: Diese Datei enthält Konfigurationsoptionen zur Steuerung des Verhaltens der Plug-ins prometheus und prometheus_monitor. Das Plug-in prometheus_monitor überwacht die Kerninfrastruktur von Fluentd. Das Plug-in prometheus stellt die Messwerte einschließlich der Messwerte aus dem Plug-in prometheus_monitor und der Messwerte aus dem obigen Plug-in google_cloud über einen lokalen Port im Prometheus-Format bereit. Weitere Einzelheiten finden Sie unter https://docs.fluentd.org/deployment/monitoring-prometheus.

• Rufen Sie das Konfigurations-Repository auf.

Für das Monitoring von Fluentd ist der integrierte Prometheus-HTTP-Messwertserver standardmäßig aktiviert. Sie können den folgenden Abschnitt aus der Konfiguration entfernen, um diesen Endpunkt zu beenden:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

Payloads verarbeiten

Die meisten unterstützten Logs in der Standardkonfiguration des Logging-Agents stammen aus Logdateien und werden in die Logeinträge als unstrukturierte Text-/Nutzlasten übernommen.

Die einzige Ausnahme ist, dass das Eingabe-Plug-in in_forward, das ebenfalls standardmäßig aktiviert ist, nur strukturierte Logs akzeptiert und diese als strukturierte (JSON-)Nutzlasten in die Logeinträge aufnimmt. Weitere Informationen finden Sie unter Streaming von strukturierten (JSON-)Logdatensätzen über in_forward-Plug-in auf dieser Seite.

Ist die Logzeile ein serialisiertes JSON-Objekt und die Option detect_json aktiviert, wandelt das Ausgabe-Plug-in den Logeintrag in eine strukturierte (JSON-)Nutzlast um. Diese Option ist standardmäßig in VM-Instanzen aktiviert, die in der flexiblen App Engine-Umgebung und Google Kubernetes Engine ausgeführt werden. Diese Option ist in VM-Instanzen, die in der App Engine-Standardumgebung ausgeführt werden, nicht standardmäßig aktiviert. Alle JSON-Elemente, die mit aktivierter Option detect_json analysiert werden, werden immer als jsonPayload aufgenommen.

Sie können die Agent-Konfiguration anpassen, um die Aufnahme strukturierter Logs aus zusätzlichen Ressourcen zu unterstützen. Weitere Informationen finden Sie unter Streaming von (JSON-)Logdatensätzen zu Cloud Logging.

Die Nutzlast von Logdatensätzen, die von einem durch einen Nutzer konfigurierten Logging-Agent gestreamt werden, kann entweder eine einzelne unstrukturierte Textnachricht (textPayload) oder eine strukturierte JSON-Nachricht (jsonPayload) sein.

Spezielle Felder in strukturierten Nutzlasten

Wenn der Logging-Agent einen strukturierten Logdatensatz empfängt, wird jeder Schlüssel verschoben, der der folgenden Tabelle im entsprechenden Feld im Objekt LogEntry entspricht. Andernfalls wird der Schlüssel Teil des Felds LogEntry.jsonPayload. Bei diesem Verhalten können Sie bestimmte Felder im Objekt LogEntry festlegen. Dies wird in die Logging API geschrieben. Wenn der strukturierte Logdatensatz beispielsweise den Schlüssel severity enthält, wird das Feld LogEntry.severity vom Logging-Agent ausgefüllt.

JSON-Logfeld	Feld LogEntry	Cloud Logging-Agent-Funktion	Beispielwert
severity	severity	Der Logging-Agent versucht, eine Übereinstimmung mit einer Vielzahl von allgemeinen Schweregrad-Strings zu finden. Dazu gehört die Liste der LogSeverity-Strings, die von der Logging API erkannt werden.	"severity":"ERROR"
message	textPayload (oder Teil von jsonPayload)	Die Nachricht, die in der Logeintragszeile im Log-Explorer angezeigt wird.	"message":"There was an error in the application." Hinweis: message wird als textPayload gespeichert, wenn es das einzige verbleibende Feld ist, nachdem der Logging-Agent die anderen Spezialfelder verschoben hat und detect_json nicht aktiviert war. Andernfalls bleibt message in jsonPayload. detect_json gilt nicht für verwaltete Logging-Umgebungen wie Google Kubernetes Engine. 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.
log (nur Legacy-Google Kubernetes Engine)	textPayload	Gilt nur für Legacy-Google Kubernetes Engine: Wenn nach dem Verschieben von Feldern für spezielle Zwecke nur ein log-Feld bleibt, wird dieses Feld 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.	"time":"2020-10-12T07:20:50.52Z"
logging.googleapis.com/insertId	insertId	Weitere Informationen finden Sie unter insertId auf der LogEntry-Seite.	"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 LogEntry-Seite.	"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 vom Log-Explorer verwendet, um zugehörige Logeinträge zu gruppieren. Weitere Informationen finden Sie auf der LogEntry-Seite unter operation.	"logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation	sourceLocation	Speicherort des Quellcodes-Informationen zum Logeintrag, falls vorhanden. Weitere Informationen finden Sie unter LogEntrySourceLocation auf der LogEntry-Seite.	"logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId	spanId	Die Span-ID innerhalb des Trace, das mit dem Logeintrag verknüpft ist. Weitere Informationen finden Sie unter spanId auf der LogEntry-Seite.	"logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace	trace	Der Ressourcenname des mit dem Logeintrag verknüpften Trace, falls vorhanden. Weitere Informationen finden Sie unter trace auf der LogEntry-Seite.	"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Hinweis: Wenn nicht in stdout oder stderr geschrieben wird, sollte der Wert dieses Felds als projects/[PROJECT-ID]/traces/[TRACE-ID] formatiert werden, damit er vom Log Explorer und vom Trace Viewer verwendet werden kann, um Logeinträge zu gruppieren und sie im Einklang mit Traces anzuzeigen. Wenn autoformat_stackdriver_trace wahr ist und [V] dem Format des ResourceTrace traceId entspricht, hat das LogEntry-Feld trace den Wert projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/trace_sampled	traceSampled	Der Wert dieses Felds muss true oder false sein. Weitere Informationen finden Sie unter traceSampled auf der LogEntry-Seite.	"logging.googleapis.com/trace_sampled": false

Zeitbezogene Felder

Zeitbezogene Informationen zu einem Logeintrag werden im Feld timestamp des LogEntry-Objekts gespeichert:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Wenn die Quelle für einen Logeintrag strukturierte Daten sind, verwendet der Logging-Agent die folgenden Regeln, um in den Feldern des jsonPayload-Eintrags nach zeitbezogenen Informationen zu suchen:

1. Suchen Sie nach einem timestamp-Feld, das ein JSON-Objekt ist, das die Felder seconds und nanos enthält, die jeweils eine vorzeichenbehaftete Anzahl von Sekunden aus der UTC-Epoche und eine nicht negative Zahl von Sekundenbruchteilen darstellen:

   jsonPayload: {
     ...
     "timestamp": {
       "seconds": CURRENT_SECONDS,
       "nanos": CURRENT_NANOS
     }
   }
   

2. Wenn die vorherige Suche fehlschlägt, suchen Sie nach einem Paar von timestampSeconds- und timestampNanos-Feldern:

   jsonPayload: {
     ...
     "timestampSeconds": CURRENT_SECONDS,
     "timestampNanos": CURRENT_NANOS
   }
   

3. Wenn die vorherige Suche fehlschlägt, suchen Sie nach einem time-Feld, das ein String im RFC 3339-Format ist:

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

Wenn zeitbezogene Informationen gefunden werden, verwendet der Logging-Agent diese Informationen, um den Wert von LogEntry.timestamp festzulegen, und kopiert diese Informationen nicht aus dem strukturierten Datensatz in das LogEntry.jsonPayload-Objekt.

Zeitbezogene Felder, die nicht zum Festlegen des Werts des Felds LogEntry.timestamp verwendet werden, werden aus dem strukturierten Datensatz in das LogEntry.jsonPayload-Objekt kopiert. Wenn der strukturierte Datensatz beispielsweise ein timestamp-JSON-Objekt und ein time-Feld enthält, werden die Daten im timestamp-JSON-Objekt zum Festlegen des LogEntry.timestamp-Felds verwendet. Das LogEntry.jsonPayload-Objekt enthält ein time-Feld, da dieses Feld nicht zum Festlegen des LogEntry.timestamp-Werts verwendet wurde.

Agent-Konfiguration anpassen

Über die Liste der Standardlogs hinaus, die der Logging-Agent standardmäßig streamt, können Sie den Logging-Agent anpassen, um zusätzliche Logs an Logging zu senden oder die Agent-Einstellungen durch Hinzufügen von Eingabekonfigurationen anzupassen.

Die Konfigurationsdefinitionen in diesen Abschnitten beziehen sich nur auf das Ausgabe-Plug-in fluent-plugin-google-cloud und geben an, wie Logs in Cloud Logging angepasst und übernommen werden.

• Speicherorte der Hauptkonfigurationsdatei:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Wenn Sie einen Logging-Agent vor v1-5 ausführen, lautet der Speicherort: C:\GoogleStackdriverLoggingAgent\fluent.conf

• Beschreibung: Diese Datei enthält Konfigurationsoptionen zur Steuerung des Verhaltens des Ausgabe-Plug-ins fluent-plugin-google-cloud.

• Siehe das Konfigurations-Repository.

Logs aus zusätzlichen Eingaben streamen

Sie können den Logging-Agent so anpassen, dass er zusätzliche Logs an Logging sendet. Dazu müssen Sie Eingabekonfigurationen hinzufügen.

Unstrukturierte (Text-)Logs über Log-Dateien streamen

Hinweis: Dieser Abschnitt enthält ein Beispiel für einen Linux-Befehl. Wenn Sie Windows verwenden, müssen Sie die Befehlsschritte an diese Umgebung anpassen. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d ist das Konfigurationsverzeichnis des Drittanbieters für Windows. Achten Sie außerdem darauf, dass in der Konfigurationsdatei für Windows Schrägstriche (/) verwendet werden. Informationen dazu, warum dies erforderlich ist, finden Sie unter Platzhaltermuster im Pfad funktioniert unter Windows nicht.

1. Erstellen Sie in der Linux-Eingabeaufforderung eine Logdatei:

   touch /tmp/test-unstructured-log.log
   

2. Erstellen Sie im zusätzlichen Konfigurationsverzeichnis /etc/google-fluentd/config.d eine neue Konfigurationsdatei mit der Bezeichnung test-unstructured-log.conf:

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # The path of the log file.
       path /tmp/test-unstructured-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-unstructured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag unstructured-log
   </source>
   EOF
   

   Alternativ zum Erstellen einer neuen Datei können Sie Konfigurationsinformationen einer vorhandenen Konfigurationsdatei hinzufügen.

3. Starten Sie den Agent neu, um die Konfigurationsänderungen zu übernehmen:

   sudo service google-fluentd restart
   

4. Generieren Sie einen Log-Datensatz in der Log-Datei:

   echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
   

5. Prüfen Sie den Log-Explorer, um den aufgenommenen Logeintrag anzuzeigen:

   {
     insertId:  "eps2n7g1hq99qp"
     labels: {
     compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/unstructured-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"
     }
     textPayload:  "This is a log from the log file at test-unstructured-log.log"
     timestamp:  "2018-03-21T01:47:05.051902169Z"
   }
   

Streaming von strukturierten (JSON-)Logs über Logdateien

Hinweis: Dieser Abschnitt enthält ein Beispiel für einen Linux-Befehl. Wenn Sie Windows verwenden, müssen Sie die Befehlsschritte an diese Umgebung anpassen. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d ist das Konfigurationsverzeichnis des Drittanbieters für Windows. Achten Sie außerdem darauf, dass in der Konfigurationsdatei für Windows Schrägstriche (/) verwendet werden. Informationen dazu, warum dies erforderlich ist, finden Sie unter Platzhaltermuster im Pfad funktioniert unter Windows nicht.

Sie können den Logging-Agent so konfigurieren, dass jeder Logeintrag für bestimmte Logeingaben strukturiert sein muss. Sie können den Logging-Agent auch so anpassen, dass er Inhalte im JSON-Format aus einer Logdatei aufnimmt. Wenn der Agent für die Aufnahme von JSON-Inhalten konfiguriert ist, muss die Eingabe so formatiert sein, dass sich jedes JSON-Objekt auf einer neuen Zeile befindet:

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

So konfigurieren Sie den Logging-Agent für die Aufnahme von Inhalten im JSON-Format:

1. Erstellen Sie in der Linux-Eingabeaufforderung eine Logdatei:

   touch /tmp/test-structured-log.log
   

2. Erstellen Sie im zusätzlichen Konfigurationsverzeichnis /etc/google-fluentd/config.d eine neue Konfigurationsdatei mit der Bezeichnung test-structured-log.conf:

   sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'json' indicates the log is structured (JSON).
           @type json
       </parse>
       # 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>
     EOF
   

   Alternativ zum Erstellen einer neuen Datei können Sie Konfigurationsinformationen einer vorhandenen Konfigurationsdatei hinzufügen.

3. Starten Sie den Agent neu, um die Konfigurationsänderungen zu übernehmen:

   sudo service google-fluentd restart
   

4. Generieren Sie einen Log-Datensatz in der Log-Datei:

   echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
   

5. Prüfen Sie den Log-Explorer, um den aufgenommenen Logeintrag anzuzeigen:

   {
     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"
   }
   

   Filtern Sie im Log-Explorer nach Ressourcentyp und einem logName von structured-log.

Weitere Informationen zum Anpassen des Log-Eingabeformats für gängige Anwendungen von Drittanbietern finden Sie unter Allgemeine Log-Formate und Anleitungen zum Analysieren von Log-Dateien.

Streaming von strukturierten (JSON-)Logs über in_forward-Plug-in

Außerdem können Sie Logs über das Plug-in fluentd in_forward senden. fluentd-cat ist ein integriertes Tool, welches das Senden von Logs an das in_forward-Plug-in erleichtert. Weitere Details zu diesem Tool finden Sie in der fluentd-Dokumentation.

Lesen Sie die folgenden Anweisungen, um Logs über das Plug-in fluentd in_forward zu senden:

1. Führen Sie den folgenden Befehl auf der VM mit dem installierten Logging-Agent aus:

   echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
   

2. Prüfen Sie den Log-Explorer, um den aufgenommenen Logeintrag anzuzeigen:

   {
     insertId:  "1kvvmhsg1ib4689"
     jsonPayload: {
     code:  "send-log-via-fluent-cat"
     message:  "This is a log from in_forward plugin."
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
     receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T02:11:22.717692494Z"
   }
   

Streaming von strukturierten (JSON-)Log-Datensätzen aus einem Anwendungscode

Sie können Connectors in verschiedenen Sprachen aktivieren, um strukturierte Logs aus dem Anwendungscode zu senden. Weitere Informationen finden Sie in der Dokumentation zu fluentd. Diese Connectors basieren auf dem Plug-in in_forward.

Logeintrags-Labels festlegen

Mit den folgenden Konfigurationsoptionen können Sie bei der Aufnahme von Logs in Cloud Logging die Labels für LogEntry und MonitoredResource überschreiben. Alle Logeinträge sind mit überwachten Ressourcen verknüpft. Weitere Informationen finden Sie in der Liste der überwachten Cloud Logging-Ressourcentypen.

Konfigurationsname	Typ	Standard	Beschreibung
label_map	Hash	Null	label_map (angegeben als JSON-Objekt) ist eine ungeordnete Gruppe von fluentd-Feldnamen, deren Werte nicht als Teil der strukturierten Nutzlast, sondern als Labels gesendet werden. Jeder Eintrag in der Zuordnung ist ein {field_name: label_name}-Paar. Wenn field_name (wie vom Eingabe-Plug-in analysiert) gefunden wird, wird dem Logeintrag ein Label mit dem entsprechenden label_name hinzugefügt. Der Wert des Feldes wird als Wert des Labels verwendet. Die Zuordnung bietet Ihnen zusätzliche Flexibilität bei der Angabe von Labelnamen, einschließlich der Möglichkeit, Zeichen zu verwenden, die nicht als Teil von fluentd-Feldnamen zulässig wären. Gehen Sie beispielsweise zu Labels in strukturierten Logeinträgen festlegen.
labels	Hash	Null	labels (angegeben als JSON-Objekt) ist eine Gruppe benutzerdefinierter Labels, die zur Konfigurationszeit bereitgestellt werden. Sie können in jede Nachricht zusätzliche Umgebungsinformationen einfügen oder Labels anpassen, die sonst automatisch erkannt werden. Jeder Eintrag in der Zuordnung ist ein {label_name: label_value}-Paar.

Das Ausgabe-Plug-in des Logging-Agents unterstützt drei Möglichkeiten zum Festlegen von Labels für LogEntry:

• Dynamisches Ersetzen bestimmter Labels in einem strukturierten Eintrag durch unterschiedliche Labels. Weitere Informationen finden Sie unter Labels in strukturierten Logeinträgen festlegen auf dieser Seite.
• Statisch, bei jedem Auftreten eines Wertes ein Label anhängen. Weitere Informationen finden Sie auf dieser Seite unter Labels statisch festlegen.

Labels in strukturierten Log-Einträgen festlegen

Angenommen, Sie haben eine strukturierte Logeingabe so geschrieben:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

Angenommen, Sie möchten das Nutzlastfeld env in ein Metadatenlabel environment übersetzen. Fügen Sie Ihrer Ausgabe-Plug-in-Konfiguration in der Hauptkonfigurationsdatei (/etc/google-fluentd/google-fluentd.conf unter Linux oder C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf unter Windows) Folgendes hinzu:

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

Die Einstellung label_map ersetzt hier das Label env in der Nutzlast durch environment. Der generierte Logeintrag hat deshalb das Label environment mit dem Wert production.

Labels statisch festlegen

Wenn diese Informationen nicht in der Nutzlast enthalten sind und Sie einfach ein statisches Metadatenlabel namens environment hinzufügen möchten, fügen Sie in die Konfiguration des Ausgabe-Plug-ins in der Hauptkonfigurationsdatei (/etc/google-fluentd/google-fluentd.conf unter Linux oder C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf unter Windows) Folgendes ein:

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

In diesem Fall verwenden wir anstelle einer Zuordnung zum Ersetzen eines Labels durch ein anderes eine Einstellung labels, um ein Label mit einem bestimmten Literalwert an einen Logeintrag anzuhängen, unabhängig davon, ob dieser Eintrag bereits ein Label hat. Mit diesem Ansatz können auch unstrukturierte Logs gesendet werden.

Weitere Informationen zum Konfigurieren von labels, label_map und anderen Logging-Agent-Einstellungen finden Sie unter Logeintrag-Labels festlegen auf dieser Seite.

Logdatensätze ändern

Fluentd bietet integrierte Filter-Plug-ins, mit denen Logeinträge geändert werden können.

Das am häufigsten verwendete Filter-Plug-in ist filter_record_transformer. Damit können Sie:

• Logeinträgen neue Felder hinzufügen
• Felder in Logeinträgen aktualisieren
• Felder in Log-Einträgen löschen

Mit einigen Ausgabe-Plug-ins können Sie auch Logeinträge bearbeiten. Das Ausgabe-Plug-in fluent-plugin-record-reformer bietet ähnliche Funktionen wie das Filter-Plug-in filter_record_transformer. Zusätzlich können Sie Logtags ändern. Mit diesem Plug-in wird eine größere Ressourcenauslastung erwartet: Jedes Mal, wenn ein Logtag aktualisiert wird, generiert es einen neuen Logeintrag mit dem neuen Tag. Beachten Sie, dass das Feld tag in der Konfiguration erforderlich ist. Wir empfehlen Ihnen außerdem, dieses Feld zu ändern, damit Sie nicht in eine leere Schleife wechseln.

Das Ausgabe-Plug-in fluent-plugin-detect-exceptions durchsucht einen Logstream (Logdatensätze mit unstrukturiertem Text oder im JSON-Format) nach mehrzeiligen Ausnahme-Stacktraces. Wenn eine fortlaufende Sequenz von Logeinträgen einen Ausnahme-Stacktrace bildet, werden die Logeinträge als eine einzelne kombinierte Lognachricht weitergeleitet. Andernfalls wird der Logeintrag unverändert weitergeleitet.

Erweiterte (nicht standardmäßige) Konfigurationsdefinitionen

Wenn Sie die Konfiguration Ihres Logging-Agents über die Standardkonfiguration hinaus anpassen möchten, lesen Sie auf dieser Seite weiter.

Pufferbezogene Konfigurationsoptionen

Mit den folgenden Konfigurationsoptionen können Sie den internen Puffermechanismus des Logging-Agents anpassen.

Konfigurationsname	Typ	Standard	Beschreibung
buffer_type	String	buf_memory	Datensätze, die nicht schnell genug in die Logging API übertragen werden können, werden in einen Puffer verschoben. Der Puffer kann im Speicher oder in physischen Dateien enthalten sein. Empfohlener Wert: buf_file. Die Standardeinstellung buf_memory ist schnell, aber nicht dauerhaft. Es besteht das Risiko, Logs zu verlieren. Wenn buffer_type buf_file ist, muss buffer_path ebenfalls angegeben werden.
buffer_path	String	Vom Nutzer angegeben	Der Pfad, in dem Pufferblöcke gespeichert werden. Dieser Parameter ist erforderlich, wenn buffer_type file ist. Diese Konfiguration muss eindeutig sein, um eine Wettlaufsituation zu vermeiden.
buffer_queue_limit	int	64	Gibt das Längenlimit der Blockwarteschlange an. Wenn die Pufferwarteschlange so viele Blöcke erreicht, wird das Pufferverhalten von buffer_queue_full_action gesteuert. Standardmäßig werden Ausnahmen ausgelöst. Diese Option in Verbindung mit buffer_chunk_limit bestimmt den maximalen Speicherplatz, den fluentd für die Pufferung benötigt.
buffer_queue_full_action	String	exception	Steuert das Pufferverhalten, wenn die Pufferwarteschlange voll ist. Mögliche Werte: 1. exception: Auswurf von BufferQueueLimitError, wenn die Warteschlange voll ist. Wie BufferQueueLimitError behandelt wird, hängt von den Eingabe-Plug-ins ab. Das Eingabe-Plug-in in_tail zum Beispiel unterbricht das Lesen neuer Zeilen, während das Eingabe-Plug-in in_forward einen Fehler zurückgibt. 2. block: Dieser Modus stoppt den Eingabe-Plug-in-Thread, bis der Puffer wieder aufnahmefähig ist. Diese Aktion eignet sich für Batch-ähnliche Anwendungsfälle. fluentd rät davon ab, Blockaktionen zu verwenden, um BufferQueueLimitError zu vermeiden. Wenn Sie häufig einen BufferQueueLimitError haben, bedeutet dies, dass die Zielkapazität für Ihren Datenverkehr nicht ausreicht. 3. drop_oldest_chunk: Dieser Modus verwirft die ältesten Blöcke.

Projektbezogene und überwachte ressourcenbezogene Konfigurationsoptionen

Mit den folgenden Konfigurationsoptionen können Sie manuell ein Projekt und bestimmte Felder aus dem Objekt MonitoredResource angeben. Diese Werte werden vom Logging-Agent automatisch erfasst. Die manuelle Festlegung dieser Werte wird nicht empfohlen.

Konfigurationsname	Typ	Standard	Beschreibung
project_id	String	Null	Wenn angegeben, überschreibt dies die project_id, die das zugrunde liegende Google Cloud- oder AWS-Projekt angibt, in dem der Logging-Agent ausgeführt wird.
zone	String	Null	Wenn angegeben, überschreibt dies die Zone.
vm_id	String	Null	Wenn angegeben, überschreibt dies die VM-ID.
vm_name	String	Null	Wenn angegeben, überschreibt dies den VM-Namen.

Weitere Konfigurationsoptionen für das Ausgabe-Plug-in

Konfigurationsname	Typ	Standard	Beschreibung
detect_json^1	bool	false	Gibt an, ob versucht werden soll, festzustellen, ob der Logdatensatz ein Text-Logeintrag mit JSON-Inhalt ist, der analysiert werden muss. Wenn diese Option true ist und ein unstrukturierter (Text-)Logeintrag im JSON-Format erkannt wird, wird dieser geparst und als strukturierte (JSON-)Nutzlast gesendet.
coerce_to_utf8	bool	true	Gibt an, ob Nicht-UTF-8-Zeichen in Nutzerlogs zulässig sind. Wenn auf true gesetzt, wird jedes Nicht-UTF-8-Zeichen durch den durch non_utf8_replacement_string angegebenen String ersetzt. Wenn auf false gesetzt, wird jedes Nicht-UTF-8-Zeichen dazu führen, dass das Plug-in ausfällt.
require_valid_tags	bool	false	Ob Logeinträge mit ungültigen Tags abgelehnt werden. Wenn diese Option auf false gesetzt ist, werden Tags gültig, indem alle Nicht-String-Tags in einen String konvertiert werden und alle Nicht-UTF-8-Zeichen oder andere ungültige Zeichen bereinigt werden.
non_utf8_replacement_string	String	"" (Leertaste)	Wenn coerce_to_utf8 auf true gesetzt ist, wird jedes Nicht-UTF-8-Zeichen durch den hier angegebenen String ersetzt.

¹ Diese Funktion ist standardmäßig in VM-Instanzen aktiviert, die in der flexiblen App Engine-Umgebung und Google Kubernetes Engine ausgeführt werden.

Angepasste Agent-Konfiguration anwenden

Wenn Sie den Logging-Agent anpassen, können Sie eigene fluentd-Konfigurationsdateien hinzufügen:

Linux-Instanz

1. Kopieren Sie Ihre Konfigurationsdateien in das folgende Verzeichnis:

   /etc/google-fluentd/config.d/
   

   In diesem Verzeichnis fügt das Installationsskript des Logging-Agents die standardmäßigen Catchall-Konfigurationsdateien hinzu. Weitere Informationen finden Sie in Quellcode des Logging-Agents abrufen.

2. Optional. Überprüfen Sie Ihre Konfigurationsänderung mit dem folgenden Befehl:

   sudo service google-fluentd configtest
   

3. Starten Sie den Agent mit dem folgenden Befehl neu:

   sudo service google-fluentd force-reload
   

Windows-Instanz

Hinweis: Wenn Sie eine Agent-Version vor v1-5 ausführen, können Sie keine eigenen Konfigurationsdateien hinzufügen. Führen Sie ein Upgrade auf den neuesten Agent durch.

1. Kopieren Sie Ihre Konfigurationsdateien in das Unterverzeichnis config.d Ihres Agent-Installationsverzeichnisses. Wenn Sie das Standardinstallationsverzeichnis übernehmen, lautet das Verzeichnis folgendermaßen:

   C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
   

2. Starten Sie den Agent mit folgenden Befehlen über die Befehlszeile neu:

   net stop  StackdriverLogging
   net start StackdriverLogging
   

Weitere Informationen zu fluentd-Konfigurationsdateien finden Sie in der Syntaxdokumentation von fluentd für die Konfigurationsdatei.