Agent konfigurieren

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

Die meisten Nutzer müssen diese Seite nicht lesen. Lesen Sie diese Seite, wenn Folgendes zutrifft:

  • Sie interessieren sich für tiefgehende technische Details zur Konfiguration des Stackdriver Logging-Agents.

  • Sie möchten die Konfiguration des Stackdriver Logging-Agents ä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 Stackdriver Logging. Sie können den Agent so konfigurieren, dass er zusätzliche Logs streamt. Siehe hierzu den folgenden Abschnitt zu Konfiguration des Logging-Agents anpassen.

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

Syslog-Konfiguration

  • Speicherorte der Konfigurationsdateien:

    • Linux: /etc/google-fluentd/config.d/syslog.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 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. Weitere Informationen finden Sie in der fluentd-Dokumentation.
read_from_head bool true Ob man beginnt, die Logs vom Dateianfang anstatt vom Dateiende zu lesen. Weitere Informationen finden Sie in der fluentd-Dokumentation.
tag String syslog Das Logtag für diese Logeingabe.

in_forward-Eingabe-Plug-in-Konfiguration

  • Speicherorte der Konfigurationsdateien:

    • Linux: /etc/google-fluentd/config.d/forward.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\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 Drittanbieteranwendungslogs

  • Speicherorte der Konfigurationsdateien:

    • Linux: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\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. Weitere Informationen finden Sie in der fluentd-Dokumentation.
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. Weitere Informationen finden Sie in der fluentd-Dokumentation.
pos_file String Variiert je nach Anwendung Der Pfad der Positionsdatei für diese Logeingabe. fluentd protokolliert die zuletzt gelesene Position in dieser Datei. Weitere Informationen finden Sie in der fluentd-Dokumentation.
read_from_head bool true Ob man beginnt, die Logs vom Dateianfang anstatt vom Dateiende zu lesen. Weitere Informationen finden Sie in der fluentd-Dokumentation.
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.

  • Siehe das Konfigurations-Repository.

Konfigurationsname Typ Standardeinstellung Beschreibung
buffer_chunk_limit String 1M Wenn Log-Datensä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. 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 Log-Datensä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, sind über den Logging-Agent zwei Messwerte verfügbar: ein Messwert für die Anzahl der Anfragen, der die Anzahl der Logeinträge wiedergibt, die an Stackdriver Logging gesendet werden sollen, und ein Messwert für die Anzahl der aufgenommenen Einträge, der die tatsächliche Anzahl der Logeinträge wiedergibt, die erfolgreich von Stackdriver Logging aufgenommen wurden. Wenn false, werden diese Messwerte nicht verfügbar gemacht.
monitoring_type String prometheus Die Art der Überwachung. Aktuell lautet die einzige Option prometheus; später werden möglicherweise noch weitere Optionen unterstützt. Wenn für enable_monitoring der Wert true gilt und für monitoring_type der Wert prometheus, sind durch den Logging-Agent einige lokale Messwerte im Prometheus-Format unter "localhost:24231/metrics" verfügbar. Siehe Details.
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.

Nutzlasten 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 zu diesem Plug-in finden Sie unter Streaming von strukturierten (JSON-)Logdatensätzen über in_forward-Plug-in.

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.

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 Stackdriver 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 aus der Nutzlast entfernt, sofern vorhanden.

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) Wenn nach dem Entfernen von Spezialfeldern nur ein message-Feld übrig ist, wird dieses message als textPayload gespeichert. Wenn Ihr Logeintrag einen Ausnahme-Stacktrace enthält, sollte dieser im JSON-Logfeld message festgelegt werden, damit er geparst und in Stackdriver Error Reporting gespeichert werden kann.
log textPayload (oder Teil von jsonPayload) Gilt nur für Cloud Functions und Google Kubernetes Engine: Wenn nach dem Entfernen von Spezialfeldern nur ein log-Feld übrig ist, wird dieses log als textPayload gespeichert.
httpRequest httpRequest Dies ist ein strukturierter Datensatz im Format des Felds LogEntry HttpRequest.
zeitbezogene Felder timestamp Weitere Informationen finden Sie unter Zeitbezogene Felder.
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. Ist nur noch ein message-Feld vorhanden, 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 Stackdriver 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 mit dem folgenden Befehl eine Logdatei:

    $ touch /tmp/test-unstructured-log.log
    
  2. Erstellen Sie im Konfigurationsverzeichnis (/etc/google-fluentd/config.d unter Linux oder C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d unter Windows) des Drittanbieters eine neue Konfigurationsdatei mit den folgenden Konfigurationen. Alternativ können Sie die Konfiguration auch in jede vorhandene Konfigurationsdatei innerhalb der Hauptkonfigurationsdatei einfügen:

    $ sudo vim /etc/google-fluentd/config.d/test-unstructured-log.conf
    $ cat /etc/google-fluentd/config.d/test-unstructured-log.conf
    <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>
    
  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

Bei der Installation des Logging-Agents können Sie das strukturierte Logging für bestimmte Logeingaben aktivieren. Weitere Informationen finden Sie unter Strukturiertes Logging.

Außerdem können Sie den Logging-Agent so anpassen, dass eine JSON-Log-Eingabe hinzugefügt wird. Nach der Erstellung dieser Konfiguration erwartet der Agent, dass jeder Log-Datensatz ein JSON-Objekt ist:

  1. Erstellen Sie eine Logdatei:

    $ touch /tmp/test-structured-log.log
    
  2. Erstellen Sie im Konfigurationsverzeichnis (/etc/google-fluentd/config.d unter Linux oder C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d unter Windows) des Drittanbieters eine neue Konfigurationsdatei mit den folgenden Konfigurationen. Alternativ können Sie die Konfiguration auch in jede vorhandene Konfigurationsdatei innerhalb der Hauptkonfigurationsdatei einfügen:

    $ 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 '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>
    
  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"
    }
    

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.

Siehe 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 Anwendungscode zu senden. Weitere Informationen finden Sie in der fluentd-Dokumentation. 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 Stackdriver Logging die Labels für LogEntry und MonitoredResource überschreiben. Alle Logeinträge sind überwachten Ressourcen zugeordnet. Weitere Informationen finden Sie in der Liste der von Stackdriver Logging überwachten 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. Weitere Informationen finden Sie unter 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 obige Nutzlastfeld env in ein Metadaten-Label 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 Stackdriver 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 Stackdriver 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.

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, finden Sie dazu Informationen in den folgenden Abschnitten.

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