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.

Funktionsweise des Logging-Agents

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

  • 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 Standardeinstellung 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

  • 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 Standardeinstellung Beschreibung
port Ganzzahl 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

  • 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 Standardeinstellung Beschreibung
format 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 Logdatei(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.

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 Standardeinstellung 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 Ganzzahl 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.
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-Plug-in-Telemetrie.
monitoring_type String opencensus Die Art der Überwachung. Die unterstützten Optionen sind opencensus und prometheus. Weitere Informationen finden Sie unter Ausgabe-Plug-in-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 Option enable_monitoring steuert, ob das Google Cloud fluentd-Ausgabe-Plug-in seine interne Telemetriedaten 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 Statusmesswerte direkt in die Monitoring API. Die Rolle roles/monitoring.metricWriter muss dem Compute Engine-Standarddienstkonto zugewiesen sein, 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"

  • 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, damit dieser Endpunkt nicht gestartet wird:

# 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, werden die folgenden Felder in spezifischer Weise behandelt. Dadurch können Sie bestimmte Felder im Objekt LogEntry festlegen, die in die Logging API geschrieben werden.

Alle Felder in der folgenden Tabelle werden, sofern vorhanden, aus der Nutzlast entfernt.

JSON-Logfeld LogEntry-Feld Logging-Agent-Funktion
severity severity Der Logging-Agent versucht, eine Übereinstimmung mit einer Vielzahl von bekannten und wichtigen Strings zu finden. Dazu gehört die Liste der LogSeverity-Strings, die von der Logging API erkannt werden.
message textPayload (oder Teil von jsonPayload) message wird als textPayload gespeichert, wenn es das einzige verbleibende Feld ist, nachdem der Logging-Agent die anderen Spezialfelder entfernt hat, und detect_json nicht aktiviert war. 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 Cloud Error Reporting gespeichert werden kann.
log (nur Legacy-Google Kubernetes Engine) textPayload Gilt nur für Legacy-Google Kubernetes Engine: Wenn nach dem Entfernen von Feldern für spezielle Zwecke nur ein log-Feld bleibt, wird dieses log als textPayload gespeichert.
httpRequest httpRequest Dies ist ein strukturierter Datensatz im Format des Felds LogEntry HttpRequest.
zeitbezogene Felder timestamp Weitere Informationen erhalten Sie unter Zeitbezogene Felder auf dieser Seite.
logging.googleapis.com/insertId insertId
logging.googleapis.com/labels labels Der Wert dieses Felds sollte ein strukturierter Datensatz sein.
logging.googleapis.com/operation operation Der Wert dieses Felds wird auch von der Loganzeige verwendet, um zugehörige Logeinträge zu gruppieren.
logging.googleapis.com/sourceLocation sourceLocation Dies ist ein strukturierter Datensatz im Format des Felds LogEntry LogEntrySourceLocation.
logging.googleapis.com/spanId spanId
logging.googleapis.com/trace trace Der Wert dieses Felds sollte das Format projects/[PROJECT-ID]/traces/[TRACE-ID] haben, damit die Loganzeige und der Trace-Betrachter Logeinträge gruppieren und im Einklang mit Traces anzeigen können. Wenn autoformat_stackdriver_trace auf true gesetzt ist und [V] dem Format des ResourceTrace-Feldes traceId entspricht, hat das LogEntry-Feld trace den Wert projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled Der Wert dieses Felds sollte das Format true oder false haben.

Alle verbleibenden strukturierten Datensatzfelder werden Teil von jsonPayload. Wenn kein detect_json vorhanden und nur ein message-Feld übrig ist, wird der Wert dieses Felds im Logeintrag als textPayload gespeichert.

Zeitbezogene Felder

Der Logging-Agent kann zeitbezogene Felder in mehreren JSON-Formaten empfangen und verarbeiten. Wenn in einem strukturierten Datensatz eine der folgenden JSON-Zeitstempeldarstellungen vorhanden ist, entfernt der Logging-Agent die Felder aus jsonPayload und reduziert sie auf eine einzige Darstellung im Feld timestamp des Objekts LogEntry:

  • jsonPayload enthält ein Feld timestamp mit den Feldern seconds und nanos, die eine vorzeichenbehaftete Anzahl von Sekunden aus der UTC-Epoche und eine nicht negative Anzahl von Sekundenbruchteilen darstellen.

    {
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  • jsonPayload enthält die Felder timestampSeconds und timestampNanos:

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload enthält ein Feld time, das dieselben Informationen zu Sekunden in Form eines Strings enthält, wie von RFC 3339 definiert:

    {
        "time": CURRENT_TIME_RFC3339
    }
    

Sobald der Logging-Agent eine Zeitstempeldarstellung erkennt, werden keine zeitstempelbezogenen Löschungen mehr vorgenommen. Das gilt auch, wenn zusätzliche Darstellungen zulässiger Formatierungen im strukturierten Datensatz vorhanden sind.

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

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

    touch /tmp/test-unstructured-log.log
    
  2. Erstellen Sie eine neue Konfigurationsdatei mit der Bezeichnung test-unstructured-log.conf im Konfigurationsverzeichnis /etc/google-fluentd/config.ddes Drittanbieters:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
    <source>
        @type tail
        # Format 'none' indicates the log is unstructured (text).
        format none
        # 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. Überprüfen Sie die Loganzeige, 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"
      }
    

Strukturierte (JSON-)Logs über Logdateien streamen

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 eine neue Konfigurationsdatei mit der Bezeichnung test-structured-log.conf im Konfigurationsverzeichnis /etc/google-fluentd/config.ddes Drittanbieters:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
    <source>
        @type tail
        # Format 'JSON' indicates the log is structured (JSON).
        format json
        # 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. Überprüfen Sie die Loganzeige, 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"
    }
    

    In der Loganzeige können Sie nach Ressourcentyp und einem logName von structured-log filtern.

Weitere Informationen zum Anpassen des Logeingabeformats für gängige Anwendungen von Drittanbietern finden Sie unter Allgemeine Logformate und Anleitungen zum Analysieren von Logdateien.

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. Überprüfen Sie die Loganzeige, 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-)Logdatensä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 Standardeinstellung 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:

Labels in strukturierten Logeinträ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 Logeinträ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.

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

Konfigurationsname Typ Standardeinstellung 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 Ganzzahl 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.

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 Standardeinstellung Beschreibung
project_id String Null Wenn angegeben, überschreibt dies die project_id, die das zugrunde liegende GCP- 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 Standardeinstellung Beschreibung
detect_json1 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.

1 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/
    
  2. Starten Sie den Agent mit dem folgenden Befehl neu:

    sudo service google-fluentd force-reload
    

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.

Windows-Instanz

  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.