Configure the Ops Agent

This document provides details about the Ops Agent's default and custom configurations. Read this document if any of the following applies to you:

• You want to change the configuration of the Ops Agent to achieve the following goals:

  • Turn off the built-in logging or metrics ingestion.

    • To turn off logging ingestion, see Example logging service configurations.

    • To turn off host-metrics ingestion, see Example metrics service configurations.

  • Customize the file path of the log files that the agent collects logs from; see Logging receivers.

  • Customize the structured log format that the agent uses to process the log entries, by parsing the JSON or by using regular expressions; see Logging processors.

  • Change the sampling rate for metrics; see Metrics receivers.

  • Customize which group or groups of metrics to enable. The agent collects all system metrics, like cpu and memory, by default; see Metrics processors.

  • Customize how the agent rotates logs; see Log-rotation configuration.

  • Collect metrics and logs from supported third-party applications. See Monitor third-party applications for the list of supported applications.

  • Use the Prometheus receiver to collect custom metrics.

  • Use the OpenTelemetry Protocol (OTLP) receiver to collect custom metrics and traces.

• You're interested in learning the technical details of the Ops Agent's configuration.

Configuration model

The Ops Agent uses a built-in default configuration; you can't directly modify this built-in configuration. Instead, you create a file of overrides that are merged with the built-in configuration when the agent restarts.

The building blocks of the configuration are as follows:

• receivers: This element describes what is collected by the agent.
• processors: This element describes how the agent can modify the collected information.
• service: This element links receivers and processors together to create data flows, called pipelines. The service element contains a pipelines element, which can contain multiple pipelines.

The built-in configuration is made up of these elements, and you use the same elements to override that built-in configuration.

Built-in configuration

The built-in configuration for the Ops Agent defines the default collection for logs and metrics. The following shows the built-in configuration for Linux and for 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]

These configurations are discussed in more detail in Logging configuration and Metrics configuration.

User-specified configuration

To override the built-in configuration, you add new configuration elements to the user configuration file. Put your configuration for the Ops Agent in the following files:

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

Any user-specified configuration is merged with the built-in configuration when the agent restarts.

To override a built-in receiver, processor, or pipeline, redefine it in your config.yaml file by declaring it with the same identifier. Starting with Ops Agent version 2.31.0, you can also configure the agent's log-rotation feature; for more information, see Configure log rotation in the Ops Agent.

For example, the built-in configuration for metrics includes a hostmetrics receiver that specifies a 60-second collection interval. To change the collection interval for host metrics to 30 seconds, include a metrics receiver called hostmetrics in your config.yaml file that sets the collection_interval value to 30 seconds, as shown in the following example:

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

For other examples of changing the built-in configurations, see Logging configuration and Metrics configuration. You can also turn off the collection of logging or metric data. These changes are described in the example logging service configurations and metrics service configurations.

You can use this file to prevent the agent from collecting self logs and sending those logs to Cloud Logging. For more information, see Collection of self logs.

You also configure the agent's log-rotation feature by using this file; for more information, see Configure log rotation in the Ops Agent.

You can't configure the Ops Agent to export logs or metrics to services other than Cloud Logging and Cloud Monitoring.

Logging configurations

The logging configuration uses the configuration model described previously:

• receivers: This element describes the data to collect from log files; this data is mapped into a <timestamp, record> model.
• processors: This optional element describes how the agent can modify the collected information.
• service: This element links receivers and processors together to create data flows, called pipelines. The service element contains a pipelines element, which can include multiple pipeline definitions.

Each receiver and each processor can be used in multiple pipelines.

The following sections describe each of these elements.

The Ops Agent sends logs to Cloud Logging. You can't configure it to export logs to other services. You can, however, configure Cloud Logging to export logs; for more information, see Route logs to supported destinations.

Logging receivers

The receivers element contains a set of receivers, each identified by a RECEIVER_ID. A receiver describes how to retrieve the logs; for example, by tailing files, by using a TCP port, or from the Windows Event Log.

Structure of logging receivers

Each receiver must have an identifier, RECEIVER_ID, and include a type element. The valid types are:

• files: Collect logs by tailing files on disk.
• fluent_forward (Ops Agent versions 2.12.0 and later): Collect logs sent via the Fluent Forward protocol over TCP.
• tcp (Ops Agent versions 2.3.0 and later): Collect logs in JSON format by listening to a TCP port.
• Linux only:
  • syslog: Collect Syslog messages over TCP or UDP.
  • systemd_journald (Ops Agent versions 2.4.0 and later): Collect systemd journal logs from the systemd-journald service.
• Windows only:
  • windows_event_log: Collect Windows Event Logs using the Windows Event Log API.
• Third-party application log receivers

The receivers structure looks like the following:

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

Depending on the value of the type element, there might be other configuration options, as follows:

• files receivers:

  • include_paths: Required. A list of filesystem paths to read by tailing each file. A wildcard (*) can be used in the paths; for example, /var/log/*.log (Linux) or C:\logs\*.log (Windows).

    For a list of common Linux application log files, see Common Linux log files.

  • exclude_paths: Optional. A list of filesystem path patterns to exclude from the set matched by include_paths.

  • record_log_file_path: Optional. If set to true, then the path to the specific file from which the log record was obtained appears in the output log entry as the value of the agent.googleapis.com/log_file_path label. When using a wildcard, only the path of the file from which the record was obtained is recorded.

  • wildcard_refresh_interval: Optional. The interval at which wildcard file paths in include_paths are refreshed. Given as a time duration, for example, 30s, 2m. This property might be useful under high logging throughputs where log files are rotated faster than the default interval. If not specified, the default interval is 60 seconds.

• fluent_forward receivers:

  • listen_host: Optional. An IP address to listen on. The default value is 127.0.0.1.

  • listen_port: Optional. A port to listen on. The default value is 24224.

• syslog receivers (for Linux only):

  • transport_protocol: Supported values: tcp, udp.

  • listen_host: An IP address to listen on.

  • listen_port: A port to listen on.

• tcp receivers:

  • format: Required. Log format. Supported value: json.

  • listen_host: Optional. An IP address to listen on. The default value is 127.0.0.1.

  • listen_port: Optional. A port to listen on. The default value is 5170.

• windows_event_log receivers (for Windows only):

  • channels: Required. A list of Windows Event Log channels from which to read logs.

  • receiver_version: Optional. Controls which Windows Event Log API to use. Supported values are 1 and 2. The default value is 1.

  • render_as_xml: Optional. If set to true, then all Event Log fields, except for jsonPayload.Message and jsonPayload.StringInserts, are rendered as an XML document in a string field named jsonPayload.raw_xml. The default value is false. This cannot be set to true when receiver_version is 1.

Examples of logging receivers

Sample files receiver:

receivers:
  RECEIVER_ID:
    type: files

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

Sample fluent_forward receiver:

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

Sample syslog receiver (Linux only):

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

Sample tcp receiver:

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

Sample windows_event_log receiver (Windows only):

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

Sample windows_event_log receiver that overrides the built-in receiver to use version 2:

receivers:
  windows_event_log:
    type: windows_event_log

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

Sample systemd_journald receiver:

receivers:
  RECEIVER_ID:
    type: systemd_journald

Special fields in structured payloads

For processors and receivers that can ingest structured data (the fluent_forward and tcp receivers and the parse_json processor), you can set special fields in the input that will map to specific fields in the LogEntry object that the agent writes to the Logging API.

When the Ops Agent receives external structured log data, it places top-level fields into the LogEntry's jsonPayload field unless the field name is listed in the following table:

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

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

Any remaining structured record fields remain part of the jsonPayload structure.

Common Linux log files

The following table lists common log files for frequently used Linux applications: