Ops-Agent konfigurieren

Dieses Dokument enthält Details zu den standardmäßigen und benutzerdefinierten Konfigurationen des Ops-Agents. Lesen Sie dieses Dokument, wenn einer der folgenden Punkte auf Sie zutrifft:

• Sie möchten die Konfiguration des Ops-Agents ändern, um folgende Ziele zu erreichen:

  • Integrierte Aufnahme von Logging oder Messwerten deaktivieren.

    • Informationen zum Deaktivieren der Logging-Aufnahme finden Sie unter Beispiele für Logging-service-Konfigurationen.

    • Informationen zum Deaktivieren der Hostmesswert-Aufnahme finden Sie unter Beispielmesswerte-service-Konfigurationen.

  • Passen Sie den Dateipfad der Logdateien an, aus denen der Agent Logs erfasst. Siehe Logging-Empfänger.

  • Passen Sie das strukturierte Logformat an, das der Agent zum Verarbeiten der Logeinträge verwendet. Parsen Sie dazu das JSON-Format oder verwenden Sie reguläre Ausdrücke. Siehe Logging-Prozessoren.

  • Weitere Informationen zum Ändern der Sampling-Rate für Messwerte ändern finden Sie unter Messwertempfänger.

  • Legen Sie fest, welche Gruppe oder Gruppen von Messwerten aktiviert werden sollen. Der Agent erfasst standardmäßig alle Systemmesswerte, wie cpu und memory. Siehe Messwertprozessoren.

  • Passen Sie an, wie der Agent Logs rotiert. Siehe Konfiguration der Logrotation.

  • Erfassen Sie Messwerte und Logs aus unterstützten Drittanbieteranwendungen. Eine Liste der unterstützten Anwendungen finden Sie unter Anwendungen von Drittanbietern beobachten.

  • Verwenden Sie den Prometheus-Empfänger, um benutzerdefinierte Messwerte zu erfassen.

  • Verwenden Sie den OpenTelemetry Protocol-Empfänger (OTLP), um benutzerdefinierte Messwerte und Traces zu erfassen.

• Sie interessieren sich für die technischen Details der Konfiguration des Ops-Agents.

Konfigurationsmodell

Der Ops-Agent verwendet eine integrierte Standardkonfiguration. Sie können diese integrierte Konfiguration nicht direkt ändern. Stattdessen erstellen Sie eine Datei mit Überschreibungen, die bei einem Neustart des Agents mit der integrierten Konfiguration zusammengeführt werden.

Die Konfiguration hat folgende Bausteine:

• receivers: Dieses Element beschreibt, was der Agent erfasst.
• processors: Dieses Element beschreibt, wie der Agent die erfassten Informationen ändern kann.
• service: Dieses Element verknüpft Empfänger und Prozessoren zu Datenflüssen, die als Pipelines bezeichnet werden. Das service-Element enthält ein pipelines-Element, das mehrere Pipelines enthalten kann.

Die integrierte Konfiguration besteht aus diesen Elementen. Sie verwenden dieselben Elemente, um diese integrierte Konfiguration zu überschreiben.

Integrierte Konfiguration

Die integrierte Konfiguration für den Ops-Agent definiert die Standardsammlung für Logs und Messwerte. Im Folgenden sehen Sie die integrierte Konfiguration für Linux und Windows:

logging:
  receivers:
    syslog:
      type: files
      include_paths:
      - /var/log/messages
      - /var/log/syslog
  service:
    pipelines:
      default_pipeline:
        receivers: [syslog]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics]
        processors: [metrics_filter]

logging:
  receivers:
    windows_event_log:
      type: windows_event_log
      channels: [System, Application, Security]
  service:
    pipelines:
      default_pipeline:
        receivers: [windows_event_log]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
    iis:
      type: iis
      collection_interval: 60s
    mssql:
      type: mssql
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics, iis, mssql]
        processors: [metrics_filter]

Diese Konfigurationen werden in der Logging-Konfiguration und der Messwertkonfiguration ausführlicher erläutert.

Vom Nutzer angegeben Konfiguration

Wenn Sie die integrierte Konfiguration überschreiben möchten, fügen Sie der Nutzerkonfigurationsdatei neue Konfigurationselemente hinzu. Fügen Sie Ihre Konfiguration für den Ops-Agent in die folgenden Dateien ein:

• Für Linux: /etc/google-cloud-ops-agent/config.yaml
• Für Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Jede benutzerdefinierte Konfiguration wird beim Neustart des Agents mit der integrierten Konfiguration zusammengeführt.

Wenn Sie einen integrierten Empfänger, Prozessor oder Pipeline überschreiben möchten, definieren Sie sie in Ihrer config.yaml-Datei neu, indem Sie sie mit derselben Kennzeichnung deklarieren. Ab der Ops-Agent-Version 2.31.0 können Sie auch die Logrotation-Funktion des Agents konfigurieren; Weitere Informationen finden Sie unter Logrotation im Ops-Agent konfigurieren.

Die integrierte Konfiguration für Messwerte enthält beispielsweise einen hostmetrics-Empfänger, der ein Erfassungsintervall von 60 Sekunden angibt. So ändern Sie das Erfassungsintervall für Hostmesswerte in 30 Sekunden: Fügen Sie der Datei config.yaml einen Messwertempfänger mit dem Namen hostmetrics hinzu, der den Wert collection_interval auf 30 Sekunden festlegt. Beispiel:

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 30s

Weitere Beispiele zum Ändern der integrierten Konfigurationen finden Sie unter Logging-Konfiguration und Messwertkonfiguration. Sie können auch die Erfassung von Logging- oder Messwertdaten deaktivieren. Diese Änderungen werden in den Beispielen für Logging-service-Konfigurationen und Messwert-service-Konfigurationen beschrieben.

Mit dieser Datei können Sie verhindern, dass der Agent Self-Logs erfasst und an Cloud Logging sendet. Weitere Informationen finden Sie unter Erfassung von Self-Logs.

Sie konfigurieren auch das Logrotation-Feature des Agents mithilfe dieser Datei. Weitere Informationen finden Sie unter Logrotation im Ops-Agent konfigurieren.

Sie können den Ops-Agent nicht so konfigurieren, dass Logs oder Messwerte in andere Dienste als Cloud Logging und Cloud Monitoring exportiert werden.

Logging-Konfigurationen

Die logging-Konfiguration verwendet das zuvor beschriebene Konfigurationsmodell:

• receivers: Dieses Element beschreibt die aus Logdateien zu erfassenden Daten. Diese Daten werden einem <timestamp, record>-Modell zugeordnet.
• processors: Dieses optionale Element beschreibt, wie der Agent die erfassten Informationen ändern kann.
• service: Dieses Element verknüpft Empfänger und Prozessoren zu Datenflüssen, die als Pipelines bezeichnet werden. Das service-Element enthält ein pipelines-Element, das mehrere Pipelinedefinitionen enthalten kann.

Jeder Empfänger und jeder Prozessor kann in mehreren Pipelines verwendet werden.

In den folgenden Abschnitten werden die einzelnen Elemente beschrieben.

Der Ops-Agent sendet Logs an Cloud Logging. Sie können ihn nicht so konfigurieren, dass Logs in andere Dienste exportiert werden. Sie können Cloud Logging jedoch so konfigurieren, dass Logs exportiert werden. Weitere Informationen finden Sie unter Logs an unterstützte Ziele weiterleiten.

Logging-Empfänger

Das receivers-Element enthält eine Reihe von Empfängern, die jeweils durch ein RECEIVER_ID identifiziert werden. Ein Empfänger beschreibt, wie die Logs abgerufen werden, beispielsweise durch Tailing von Dateien, mithilfe eines TCP-Ports oder aus dem Windows-Ereignislog.

Struktur von Logging-Empfängern

Jeder Empfänger muss die Kennzeichnung RECEIVER_ID haben und ein type-Element enthalten. Gültige Typen:

• files: Erfassen Sie Logs durch Tailing von Dateien auf dem Laufwerk.
• fluent_forward (verfügbar mit Ops-Agent-Versionen ab 2.12.0): Erfassen Sie Logs, die mit dem Fluent Forward-Protokoll über TCP gesendet werden.
• tcp (Ops-Agent-Versionen ab 2.3.0): Erfassen Sie Logs im JSON-Format durch Überwachen eines TCP-Ports erfassen.
• Nur Linux:
  • syslog: Erfassen Sie Syslog-Nachrichten über TCP oder UDP.
  • systemd_journald (Ops-Agent-Versionen ab 2.4.0): Erfassen Sie Systemd-Journallogs aus dem Dienst systemd-journald.
• (nur Windows):
  • windows_event_log: Erfassen Sie Windows-Ereignislogs mit der Windows Event Log API.
• Empfänger der Anwendungslogs von Drittanbietern

Die receivers-Struktur sieht so aus:

receivers:
  RECEIVER_ID:
    type: files
    ...
  RECEIVER_ID_2:
    type: syslog
    ...

Je nach Wert des Elements type gibt es möglicherweise weitere Konfigurationsoptionen:

• files Empfänger:

  • include_paths: erforderlich. Eine Liste mit Dateisystempfaden, die durch Tailing jeder Datei gelesen werden sollen. In den Pfaden kann ein Platzhalter (*) verwendet werden. Beispiel: /var/log/*.log (Linux) oder C:\logs\*.log (Windows).

    Eine Liste häufig verwendeter Linux-Anwendungslogdateien finden Sie unter Häufig verwendete Linux-Logdateien.

  • exclude_paths: Optional. Eine Liste von Dateisystempfadmustern, die aus dem mit include_paths übereinstimmenden Satz ausgeschlossen werden sollen.

  • record_log_file_path: Optional. Wenn true festgelegt ist, wird der Pfad zu der spezifischen Datei, aus der der Logdatensatz abgerufen wurde, im Ausgabelogeintrag als Wert des Labels agent.googleapis.com/log_file_path angezeigt. Bei Verwendung eines Platzhalters wird nur der Pfad der Datei aufgezeichnet, aus der der Eintrag abgerufen wurde.

  • wildcard_refresh_interval: Optional. Das Intervall, in dem Platzhalterdateipfade in include_paths aktualisiert werden. Wird als Zeitdauer angegeben, z. B. 30s, 2m. Dieses Attribut kann bei hohen Logging-Durchsätzen nützlich sein, wenn Logdateien schneller als das Standardintervall rotiert werden. Wenn keine Angabe erfolgt, beträgt das Standardintervall 60 Sekunden.

• fluent_forward Empfänger:

  • listen_host: Optional. Eine IP-Adresse, die überwacht werden soll. Der Standardwert ist 127.0.0.1.

  • listen_port: Optional. Ein Port, der überwacht werden soll. Der Standardwert ist 24224.

• syslog-Empfänger (nur für Linux):

  • transport_protocol: Unterstützte Werte: tcp, udp.

  • listen_host: Eine IP-Adresse, auf die gelauscht werden soll.

  • listen_port: Ein Port, der überwacht werden soll.

• tcp Empfänger:

  • format: erforderlich. Logformat Unterstützter Wert: json.

  • listen_host: Optional. Eine IP-Adresse, die überwacht werden soll. Der Standardwert ist 127.0.0.1.

  • listen_port: Optional. Ein Port, der überwacht werden soll. Der Standardwert ist 5170.

• windows_event_log-Empfänger (nur für Windows):

  • channels: erforderlich. Eine Liste der Windows-Ereignis-Log-Kanäle, aus denen Logs gelesen werden sollen.

  • receiver_version: Optional. Steuert, welche Windows Event Log API verwendet werden soll. Unterstützte Werte sind 1 und 2. Der Standardwert ist 1.

  • render_as_xml: Optional. Wenn true festgelegt ist, werden alle Ereignisprotokollfelder mit Ausnahme von jsonPayload.Message und jsonPayload.StringInserts als XML-Dokument in einem Stringfeld namens jsonPayload.raw_xml gerendert. Der Standardwert ist false. Er kann nicht auf true gesetzt werden, wenn receiver_version gleich 1 ist.

Beispiele für Logging-Empfänger

Beispiel-files-Empfänger:

receivers:
  RECEIVER_ID:
    type: files

    include_paths: [/var/log/*.log]
    exclude_paths: [/var/log/not-this-one.log]
    record_log_file_path: true

Beispiel-fluent_forward-Empfänger:

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

Beispiel-syslog-Empfänger (nur Linux):

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

Beispiel-tcp-Empfänger:

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

Beispiel-windows_event_log-Empfänger (nur Windows):

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

Beispiel-windows_event_log-Empfänger, der den integrierten Empfänger überschreibt, um die Version 2 zu verwenden:

receivers:
  windows_event_log:
    type: windows_event_log

    channels: [System,Application,Security]
    receiver_version: 2

Beispiel-systemd_journald-Empfänger:

receivers:
  RECEIVER_ID:
    type: systemd_journald

Spezielle Felder in strukturierten Nutzlasten

Für Prozessoren und Empfänger, die strukturierte Daten aufnehmen können (die Empfänger fluent_forward und tcp und der Prozessor parse_json), können Sie in der Eingabe spezielle Felder festlegen, die speziellen Feldern im Objekt LogEntry zugeordnet sind, das der Agent in die Logging API schreibt.

Wenn der Ops-Agent externe strukturierte Logdaten empfängt, werden die Felder der obersten Ebene in das Feld jsonPayload von LogEntry eingefügt, sofern der Feldname nicht in der folgenden Tabelle aufgeführt ist:

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

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

Alle verbleibenden strukturierten Eintragsfelder bleiben Teil der jsonPayload-Struktur.

Häufig verwendete Linux-Logdateien

In der folgenden Tabelle sind häufig verwendete Logdateien für häufig verwendete Linux-Anwendungen aufgeführt:

Standardlabels für aufgenommene Daten

Logs können standardmäßig die folgenden Labels im LogEntry enthalten:

Logging-Prozessoren

Das optionale Element processors enthält eine Reihe von Verarbeitungsanweisungen, die jeweils durch eine PROCESSOR_ID identifiziert werden. Ein Prozessor beschreibt, wie die von einem Empfänger erfassten Informationen bearbeitet werden.

Jeder Prozessor muss eine eindeutige Kennzeichnung haben und ein type-Element enthalten. Gültige Typen:

• parse_json: Parst strukturierte Logs im JSON-Format.
• parse_multiline: Parst mehrzeilige Logs. (Nur Linux)
• parse_regex: Parst Logs im Textformat über Regex-Muster, um sie in strukturierte Logs im JSON-Format zu konvertieren.
• exclude_logs: Schließt Logs aus, die bestimmten Regeln entsprechen (ab 2.9.0).
• modify_fields: Felder in Logeinträgen festlegen/transformieren (ab 2.14.0).

Die processors-Struktur sieht so aus:

processors:
  PROCESSOR_ID:
    type: parse_json
    ...
  PROCESSOR_ID_2:
    type: parse_regex
    ...

Je nach Wert des Elements type gibt es weitere Konfigurationsoptionen.

Prozessor parse_json

Konfigurationsstruktur

processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    <field name within jsonPayload>
    time_format: <strptime format string>

Der Prozessor parse_json parst die JSON-Eingabe in das Feld jsonPayload von LogEntry. Andere Teile von LogEntry können geparst werden, indem spezielle Felder der obersten Ebene festgelegt werden.

• time_key: Optional. Wenn der Logeintrag ein Feld mit einem Zeitstempel bereitstellt, gibt diese Option den Namen dieses Feldes an. Der extrahierte Wert wird zum Festlegen des Felds timestamp des resultierenden LogEntry verwendet und aus der Nutzlast entfernt.

  Wenn die Option time_key angegeben ist, müssen Sie auch Folgendes angeben:

  • time_format: Erforderlich, wenn time_key verwendet wird. Mit dieser Option wird das Format des Feldes time_key angegeben, damit es erkannt und richtig analysiert werden kann. Weitere Informationen zum Format finden Sie im Leitfaden strptime(3).

Konfigurationsbeispiel

processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

Prozessor parse_multiline

Konfigurationsstruktur

processors:
  PROCESSOR_ID:
    type: parse_multiline

    match_any:
    - type: <type of the exceptions>
      language: <language name>

• match_any: erforderlich. Eine Liste mit einer oder mehreren Regeln.

  • type: erforderlich. Es wird nur ein einziger Wert unterstützt:

    • language_exceptions: Ermöglicht dem Prozessor, Ausnahmen basierend auf dem Wert der Option language zu einem LogEntry zu verketten.

  • language: erforderlich. Es wird nur ein einziger Wert unterstützt:

    • java: Verkettet gängige Java-Ausnahmen zu einem LogEntry.
    • python: Verkettet gängige Python-Ausnahmen zu einem LogEntry.
    • go: Verkettet gängige Go-Ausnahmen zu einem LogEntry.

Konfigurationsbeispiel

logging:
  receivers:
    custom_file1:
      type: files
      include_paths:
      - /tmp/test-multiline28
  processors:
    parse_java_multiline:
      type: parse_multiline
      match_any:
      - type: language_exceptions
        language: java
    extract_structure:
      type: parse_regex
      field: message
      regex: "^(?<time>[\d-]*T[\d:.Z]*) (?<severity>[^ ]*) (?<file>[^ :]*):(?<line>[\d]*) - (?<message>(.|\\n)*)$"
      time_key: time
      time_format: "%Y-%m-%dT%H:%M:%S.%L"
    move_severity:
      type: modify_fields
      fields:
        severity:
          move_from: jsonPayload.severity
  service:
    pipelines:
      pipeline1:
        receivers: [custom_file1]
        processors: [parse_java_multiline, extract_structure, move_severity]

Wenn Sie die vorherige Konfiguration verwenden und eine Logdatei mit folgendem Inhalt haben:

2022-10-17T22:00:00.187512963Z ERROR HelloWorld:16 - javax.servlet.ServletException: Something bad happened
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)
Caused by: com.example.myproject.MyProjectServletException
    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)
    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)
    ... 27 common frames omitted

erfasst der Agent die Logs im folgenden Format in Cloud Logging:

{
  "insertId": "...",
  "jsonPayload": {
    "line": "16",
    "message": "javax.servlet.ServletException: Something bad happened\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)\nCaused by: com.example.myproject.MyProjectServletException\n    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)\n    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)\n    ... 27 common frames omitted\n",
    "file": "HelloWorld"
  },
  "resource": {
    "type": "gce_instance",
    "labels": {
      "instance_id": "...",
      "project_id": "...",
      "zone": "..."
    }
  },
  "timestamp": "2022-10-17T22:00:00.187512963Z",
  "severity": "ERROR",
  "labels": {
    "compute.googleapis.com/resource_name": "..."
  },
  "logName": "projects/.../logs/custom_file",
  "receiveTimestamp": "2022-10-18T03:12:38.430364391Z"
}

Prozessor parse_regex

Konfigurationsstruktur

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

    time_key:    <field name within jsonPayload>
    time_format: <format string>

• time_key: Optional. Wenn der Logeintrag ein Feld mit einem Zeitstempel bereitstellt, gibt diese Option den Namen dieses Feldes an. Der extrahierte Wert wird zum Festlegen des Felds timestamp des resultierenden LogEntry verwendet und aus der Nutzlast entfernt.

  Wenn die Option time_key angegeben ist, müssen Sie auch Folgendes angeben:

  • time_format: Erforderlich, wenn time_key verwendet wird. Mit dieser Option wird das Format des Feldes time_key angegeben, damit es erkannt und richtig analysiert werden kann. Weitere Informationen zum Format finden Sie im Leitfaden strptime(3).

• regex: erforderlich. Der reguläre Ausdruck zum Parsen des Feldes. Der Ausdruck muss Schlüsselnamen für die übereinstimmenden Unterausdrücke enthalten, z. B. "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$".

  Der von benannten Erfassungsgruppen übereinstimmende Text wird in Feldern im Feld jsonPayload von LogEntry abgelegt. Verwenden Sie den Prozessor modify_fields, um Ihren Logs eine zusätzliche Struktur hinzuzufügen.

  Eine Reihe regulärer Ausdrücke zum Extrahieren von Informationen aus häufig verwendeten Linux-Anwendungslogdateien finden Sie unter Häufig verwendete Linux-Logdateien.

Konfigurationsbeispiel

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex:       "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"
    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

Prozessor exclude_logs

Konfigurationsstruktur:

type: exclude_logs
match_any:
  - <filter>
  - <filter>

Die übergeordnete Konfiguration für diesen Prozessor enthält ein einzelnes Feld (match_any), das eine Liste von Filterregeln enthält.

• match_any: erforderlich. Eine Liste mit einer oder mehreren Regeln. Wenn ein Logeintrag mit einer Regel übereinstimmt, nimmt der Ops-Agent diesen Eintrag nicht auf.

  Die vom Ops-Agent aufgenommenen Logs folgen der LogEntry-Struktur. Bei Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden. Sie können Regeln nur basierend auf den folgenden Feldern und ihren Unterfeldern angeben:

  • httpRequest
  • jsonPayload
  • labels
  • operation
  • severity
  • sourceLocation
  • trace
  • spanId

  Die folgende Beispielregel

  severity =~ "(DEBUG|INFO)"
  

  verwendet einen regulären Ausdruck, um alle Logs auf DEBUG- und INFO-Ebene auszuschließen.

  Regeln folgen der Syntax der Cloud Logging-Abfragesprache, unterstützen jedoch nur einen Teil der Funktionen, die von der Logging-Abfragesprache unterstützt werden:

  • Vergleichsoperatoren: =, !=, :, =~, !~. Es werden nur Stringvergleiche unterstützt.
  • Navigationsoperator: .. Beispiel: jsonPayload.message.
  • Boolesche Operatoren: AND, OR, NOT.
  • Ausdrücke mit ( ) gruppieren.

Konfigurationsbeispiel

processors:
  PROCESSOR_ID:
    type: exclude_logs
    match_any:
    - '(jsonPayload.message =~ "log spam 1" OR jsonPayload.message =~ "log spam 2") AND severity = "ERROR"'
    - 'jsonPayload.application = "foo" AND severity = "INFO"'

Prozessor modify_fields

Der Prozessor modify_fields ermöglicht die Anpassung der Struktur und des Inhalts von Logeinträgen.

Konfigurationsstruktur

type: modify_fields
fields:
  <destination field>:
    # Source
    move_from: <source field>
    copy_from: <source field>
    static_value: <string>
    
    # Mutation
    default_value: <string>
    map_values:
      <old value>: <new value>
    type: {integer|float}
    omit_if: <filter>

Die übergeordnete Konfiguration für diesen Prozessor enthält ein einzelnes Feld (fields), das eine Zuordnung von Ausgabefeldnamen und entsprechenden Übersetzungen enthält. Für jedes Ausgabefeld werden eine optionale Quelle und null oder mehr Mutationsvorgänge angewendet.

Alle Feldnamen verwenden die durch Punkte getrennte Syntax aus der Cloud Logging-Abfragesprache. Filter verwenden die Cloud Logging-Abfragesprache.

Alle Transformationen werden parallel angewendet. Das bedeutet, dass Quellen und Filter den ursprünglichen Eingabe-Logeintrag bearbeiten und daher nicht auf den neuen Wert anderer Felder verweisen können, die vom selben Prozessor geändert werden.

Quelloptionen: Es ist höchstens eine angegebene Quelle zulässig.

• Keine Quelle angegeben

  Wenn kein Quellwert angegeben ist, wird der vorhandene Wert im Zielfeld geändert.

• move_from: <source field>

  Der Wert von <source field> wird als Quelle für das Zielfeld verwendet. Darüber hinaus wird <source field> aus dem Logeintrag entfernt. Wenn auf ein Quellfeld sowohl von move_from als auch von copy_from verwiesen wird, wird das Quellfeld entfernt.

• copy_from: <source field>

  Der Wert von <source field> wird als Quelle für das Zielfeld verwendet. <source field> wird nur dann aus dem Logeintrag entfernt, wenn es auch von einem move_from-Vorgang referenziert oder anderweitig geändert wird.

• static_value: <string>

  Der statische String <string> wird als Quelle für das Zielfeld verwendet.

Mutationsoptionen: Es können null oder mehr Mutationsoperatoren auf ein einzelnes Feld angewendet werden. Wenn mehrere Operatoren angegeben sind, werden diese immer in der folgenden Reihenfolge angewendet.

1. default_value: <string>

   Wenn das Quellfeld nicht vorhanden war, wird der Ausgabewert auf <string> gesetzt. Wenn das Quellfeld bereits vorhanden ist (auch wenn es einen leeren String enthält), wird der ursprüngliche Wert nicht geändert.

2. map_values: <map>

   Wenn der Eingabewert mit einem der Schlüssel in <map> übereinstimmt, wird der Ausgabewert durch den entsprechenden Wert aus der Zuordnung ersetzt.

3. map_values_exclusive: {true|false}

   Wenn der <source field>-Wert mit keinem in den map_values-Paaren angegebenen Schlüsseln übereinstimmt, wird das Zielfeld zwangsweise nicht festgelegt, wenn map_values_exclusive "true" ist oder es bleibt unverändert, wenn map_values_exclusive "false" ist.

4. type: {integer|float}

   Der Eingabewert wird in eine Ganzzahl oder eine Gleitkommazahl konvertiert. Wenn der String nicht in eine Zahl umgewandelt werden kann, wird der Ausgabewert nicht festgelegt. Wenn der String eine Gleitkommazahl enthält, der Typ aber als integer angegeben ist, wird die Zahl auf eine Ganzzahl gekürzt.

   Beachten Sie, dass die Cloud Logging API JSON verwendet und daher keine vollständige 64-Bit-Ganzzahl unterstützt. Wenn eine 64-Bit-Ganzzahl (oder größer) erforderlich ist, muss sie als String im Logeintrag gespeichert werden.

5. omit_if: <filter>

   Wenn der Filter mit dem Eintrag des Eingabelogs übereinstimmt, wird das Ausgabefeld nicht festgelegt. So können Sie Platzhalterwerte entfernen, z. B.:

   httpRequest.referer:
     move_from: jsonPayload.referer
     omit_if: httpRequest.referer = "-"
   

Beispielkonfigurationen

Der Prozessor parse_json würde eine JSON-Datei mit dem Inhalt

{
  "http_status": "400",
  "path": "/index.html",
  "referer": "-"
}

in eine LogEntry-Struktur transformieren, die so aussieht:

{
  "jsonPayload": {
    "http_status": "400",
    "path": "/index.html",
    "referer": "-"
  }
}

Dies könnte dann mit modify_fields in diesen LogEntry transformiert werden:

{
  "httpRequest": {
    "status": 400,
    "requestUrl": "/index.html",
  }
}

Verwenden Sie dazu diese Ops-Agent-Konfiguration:

logging:
  receivers:
    in:
      type: files
      include_paths:
      - /var/log/http.json
  processors:
    parse_json:
      type: parse_json
    set_http_request:
      type: modify_fields
      fields:
        httpRequest.status:
          move_from: jsonPayload.http_status
          type: integer
        httpRequest.requestUrl:
          move_from: jsonPayload.path
        httpRequest.referer:
          move_from: jsonPayload.referer
          omit_if: jsonPayload.referer = "-"
  service:
    pipelines:
      pipeline:
        receivers: [in]
        processors: [parse_json, set_http_request]

Diese Konfiguration liest JSON-formatierte Logs aus /var/log/http.json und füllt einen Teil der Struktur httpRequest aus Feldern in den Logs aus.

Logging-Dienst

Der Logging-Dienst passt die Ausführlichkeit für die eigenen Logs des Ops-Agents an und verknüpft Logging-Empfänger und -Prozessoren zu Pipelines. Der Abschnitt service enthält die folgenden Elemente:

• log_level
• pipelines

Ausführlichkeitsstufe für Logs

log_level ist ab Ops-Agent-Version 2.6.0 verfügbar und passt die Ausführlichkeit für die eigenen Logs des Logging-Submoduls des Ops-Agents an. Der Standardwert ist info. Folgende Optionen sind verfügbar: error, warn, info, debug, trace.

Die folgende Konfiguration passt die Log-Ausführlichkeit für das Logging-Untermodul stattdessen auf debug an:

logging:
  service:
    log_level: debug

Logging-Pipelines

Das Feld pipelines kann mehrere Pipeline-IDs und Definitionen enthalten. Jeder pipeline-Wert besteht aus den folgenden Elementen:

• receivers: Für neue Pipelines erforderlich. Eine Liste von Empfänger-IDs, wie unter Logging-Empfänger beschrieben. Die Reihenfolge der Empfänger-IDs in der Liste spielt keine Rolle. Die Pipeline erfasst Daten von allen aufgelisteten Empfängern.

• processors: Optional. Eine Liste von Prozessor-IDs, wie unter Logging-Prozessoren beschrieben. Die Reihenfolge der Prozessor-IDs in der Liste ist wichtig. Jeder Eintrag wird von den Prozessoren in der aufgeführten Reihenfolge ausgeführt.

Beispiele für Logging-service-Konfigurationen

Eine service-Konfiguration hat die folgende Struktur:

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

Wenn Sie verhindern möchten, dass der Agent /var/log/message- oder /var/log/syslog-Einträge erfasst und sendet, definieren Sie die Standardpipeline mit einer leeren receivers-Liste und ohne Prozessoren neu. Durch diese Konfiguration wird die Logging-Unterkomponente des Agents nicht angehalten, da der Agent Logs für die Monitoring-Unterkomponente erfassen muss. Die gesamte leere Logging-Konfiguration sieht so aus:

logging:
  service:
    pipelines:
      default_pipeline:
        receivers: []

Die folgende service-Konfiguration definiert eine Pipeline mit der ID custom_pipeline:

logging:
  service:
    pipelines:
      custom_pipeline:
        receivers:
        - RECEIVER_ID
        processors:
        - PROCESSOR_ID

Messwertkonfigurationen

Die metrics-Konfiguration verwendet das zuvor beschriebene Konfigurationsmodell:

• receivers: Eine Liste der Empfängerdefinitionen. Ein receiver beschreibt die Quelle der Messwerte, beispielsweise die Systemmesswerte cpu oder memory. Die Empfänger in dieser Liste können von mehreren Pipelines gemeinsam genutzt werden.
• processors: Eine Liste von Prozessordefinitionen. Ein processor beschreibt, wie die von einem Empfänger erfassten Messwerte geändert werden.
• service: Enthält einen pipelines-Abschnitt, der eine Liste von pipeline-Definitionen enthält. Eine pipeline verbindet für einen Datenfluss eine Liste von receivers mit einer Liste von processors, um den Datenfluss zu bilden.

In den folgenden Abschnitten werden die einzelnen Elemente beschrieben.

Der Ops-Agent sendet Messwerte an Cloud Monitoring. Sie können ihn nicht so konfigurieren, dass Messwerte in andere Dienste exportiert werden.

Messwertempfänger

Das receivers-Element enthält eine Reihe von Empfängerdefinitionen. Ein Empfänger beschreibt, wo die Messwerte abgerufen werden, z. B. cpu und memory. Ein Empfänger kann von mehreren Pipelines gemeinsam genutzt werden.

Struktur von Messwertempfängern

Jeder Empfänger muss die Kennzeichnung RECEIVER_ID haben und ein type-Element enthalten. Gültige integrierte Typen sind:

• hostmetrics
• iis (Nur Windows)
• mssql (Nur Windows)

Ein Empfänger kann auch die Option collection_interval angeben. Der Wert hat das Format einer Dauer, z .B. 30s oder 2m. Der Standardwert ist 60s.

Jeder dieser Empfängertypen erfasst eine Reihe von Messwerten. Informationen zu den jeweiligen Messwerten finden Sie unter Von den Empfängern aufgenommene Messwerte.

Sie können nur einen Empfänger pro Typ erstellen. Beispielsweise können Sie nicht zwei Empfänger vom Typ hostmetrics definieren.

Erfassungsintervall in den Messwertempfängern ändern

Einige kritische Arbeitslasten erfordern möglicherweise eine schnelle Benachrichtigung. Durch Reduzierung des Erfassungsintervalls für die Messwerte können Sie sensiblere Benachrichtigungen konfigurieren. Informationen zum Auswerten von Benachrichtigungen finden Sie unter Verhalten von messwertbasierten Benachrichtigungsrichtlinien.

Beispielsweise ändert der folgende Empfänger das Erfassungsintervall für Hostmesswerte (die Empfänger-ID lautet hostmetrics) vom Standardwert von 60 Sekunden in 10 Sekunden:

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 10s

Mit derselben Technik können Sie auch das Erfassungsintervall für die Messwertempfänger in Windows namens iis und mssql überschreiben.

Von den Empfängern aufgenommene Messwerte

Die vom Ops-Agent aufgenommenen Messwerte haben Kennzeichnungen, die mit dem folgenden Muster beginnen: agent.googleapis.com/GROUP. Die Komponente GROUP identifiziert eine Reihe zusammenhängender Messwerte; sie hat Werte wie cpu, network und weitere.

Der hostmetrics-Empfänger

Der hostmetrics-Empfänger nimmt die folgenden Messwertgruppen auf. Weitere Informationen finden Sie im verknüpften Abschnitt für jede Gruppe auf der Seite Ops-Agent-Messwerte.

Der Empfänger iis (nur Windows)

Der Empfänger iis (nur Windows) nimmt Messwerte der Gruppe iis auf. Weitere Informationen finden Sie auf der Seite Agent-Messwerte.

Der Empfänger mssql (nur Windows)

Der Empfänger mssql (nur Windows) nimmt Messwerte der Gruppe mssql auf. Weitere Informationen finden Sie auf der Seite Ops-Agent-Messwerte.

Messwertprozessoren

Das processor-Element enthält eine Reihe von Prozessordefinitionen. Ein Prozessor beschreibt Messwerte vom auszuschließenden Empfängertyp. Der einzige unterstützte Typ ist exclude_metrics, der die Option metrics_pattern verwendet. Der Wert ist eine Liste von Globs, die den Ops-Agent-Messwerttypen entsprechen, die Sie aus der von einem Empfänger erfassten Gruppe ausschließen möchten. Beispiel:

• Geben Sie agent.googleapis.com/cpu/* an, um alle CPU-Messwerte des Agents auszuschließen.
• Geben Sie agent.googleapis.com/cpu/utilization an, um die CPU-Auslastung des Agents auszuschließen.
• Geben Sie workloads.googleapis.com/cassandra.client.request.count an, um den clientseitigen Messwert für die Anzahl der Anfragen aus den Messwerten auszuschließen, die von der Apache Cassandra-Integration des Drittanbieters erfasst werden.
• Wenn Sie alle clientseitigen Messwerte aus den von der Apache Cassandra-Drittanbieterintegration erfassten Messwerten ausschließen möchten, geben Sie workloads.googleapis.com/cassandra.client.* an.

Beispiel für einen Messwertprozessor

Das folgende Beispiel zeigt den in den integrierten Konfigurationen bereitgestellten exclude_metrics-Prozessor. Dieser Prozessor gibt einen leeren metrics_pattern-Wert an, sodass keine Messwerte ausgeschlossen werden.

processors:
  metrics_filter:
    type: exclude_metrics
    metrics_pattern: []

Fügen Sie der Datei config.yaml Folgendes hinzu, um die Erfassung aller Prozessmesswerte durch den Ops-Agent zu deaktivieren:

metrics:
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern:
      - agent.googleapis.com/processes/*

Dies schließt Prozessmesswerte von der Erfassung im metrics_filter-Prozessor aus, die für die Standardpipeline im metrics-Dienst gilt.

Messwertdienst

Der Messwertdienst passt die Ausführlichkeit für die eigenen Logs des Ops-Agent-Messwertmoduls an und verknüpft Messwertempfänger und -prozessoren miteinander in Pipelines. Der Abschnitt service enthält zwei Elemente: log_level und pipelines.

Ausführlichkeitsstufe für Messwerte

log_level ist ab Ops-Agent-Version 2.6.0 verfügbar und passt die Ausführlichkeit für die eigenen Logs des Messwerte-Submoduls des Ops-Agent an. Der Standardwert ist info. Folgende Optionen sind verfügbar: error, warn, info, debug.

Messwertpipelines

Der Abschnitt service enthält ein einzelnes Element, pipelines, das mehrere Pipeline-IDs und Definitionen enthalten kann. Jede pipeline-Definition besteht aus den folgenden Elementen:

• receivers: Für neue Pipelines erforderlich. Eine Liste von Empfänger-IDs, wie unter Messwert-Empfänger beschrieben. Die Reihenfolge der Empfänger-IDs in der Liste spielt keine Rolle. Die Pipeline erfasst Daten von allen aufgelisteten Empfängern.

• processors: Optional. Eine Liste von Prozessor-IDs, wie unter Messwertprozessoren beschrieben. Die Reihenfolge der Prozessor-IDs in der Liste ist wichtig. Jeder Messwertpunkt wird in der aufgeführten Reihenfolge durch die Prozessoren ausgeführt.

Beispiel für service-Messwertkonfigurationen

Eine service-Konfiguration hat die folgende Struktur:

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

Wenn Sie die integrierte Aufnahme von Hostmesswerten deaktivieren möchten, definieren Sie die Standardpipeline mit einer leeren receivers-Liste ohne Prozessoren neu. Die gesamte Messwertkonfiguration sieht so aus:

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers: []

Das folgende Beispiel zeigt die integrierte service-Konfiguration für Windows:

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers:
        - hostmetrics
        - iis
        - mssql
        processors:
        - metrics_filter

Die folgende service-Konfiguration passt die Log-Ausführlichkeit für das Messwerte-Untermodul stattdessen auf debug an:

metrics:
  service:
    log_level: debug

Erfassung der eigenen Logs

Standardmäßig werden die Fluent Bit-Self-Logs des Ops-Agents an Cloud Logging gesendet. Diese Logs können viele Informationen enthalten und das zusätzliche Volumen kann die Kosten für die Nutzung von Cloud Logging erhöhen.

Ab der Ops-Agent-Version 2.44.0 können Sie die Erfassung dieser Self-Logs mithilfe der Option default_self_log_file_collection deaktivieren.

Wenn Sie die Erfassung von Self-Logs deaktivieren möchten, fügen Sie der vom Nutzer angegebenen Konfigurationsdatei den Abschnitt global hinzu und legen Sie für die Option default_self_log_file_collection den Wert false fest:

logging:  ...
metrics:  ...
global:
  default_self_log_file_collection: false

Konfiguration der Logrotation

Ab Ops-Agent-Version 2.31.0 können Sie das Logrotation-Feature des Agents auch mithilfe der Konfigurationsdateien einrichten. Weitere Informationen finden Sie unter Logrotation im Ops-Agent konfigurieren.