配置 Ops Agent

本文档详细介绍了 Ops Agent 的默认配置和自定义配置。如果以下任何一项适用于您，请阅读本文档：

您想要更改 Ops Agent 的配置以实现以下目标：
- 关闭内置日志记录或指标注入功能。
  - 如需关闭日志记录注入功能，请参阅日志记录 service 配置示例。
  - 如需关闭主机指标注入功能，请参阅指标 service 配置示例。
- 自定义代理从中收集日志的日志文件的路径；请参阅日志记录接收器。
- 通过解析 JSON 或使用正则表达式来自定义代理用于处理日志条目的结构化日志格式；请参阅日志记录处理器。
- 更改指标的采样率；请参阅指标接收器。
- 自定义要启用的一组或多组指标。默认情况下，代理会收集所有系统指标，例如 cpu 和 memory；请参阅指标处理器。
- 自定义代理轮换日志的方式。请参阅日志轮换配置。
- 从支持的第三方应用收集指标和日志。如需查看支持应用的列表，请参阅监控第三方应用。
- 使用 Prometheus 接收器收集自定义指标。
- 使用 OpenTelemetry Protocol (OTLP) 接收器收集自定义指标和跟踪记录。
您有兴趣了解 Ops Agent 配置的技术细节。

配置模型

Ops Agent 使用内置默认配置；您无法直接修改此内置配置。但是，您可以创建包含替换内容的文件，代理重启时这些替换内容会与内置配置合并。

配置的构成要素如下：

receivers：此元素描述代理要收集的信息。
processors：此元素描述代理可以如何修改收集的信息。
service：此元素将接收器和处理器连接在一起，以创建数据流，称为“流水线”。service 元素包含一个 pipelines 元素，后者可包含多个流水线。

内置配置由这些元素组成，您可以使用相同的元素来替换该内置配置。

内置配置

Ops Agent 的内置配置定义了日志和指标的默认收集。下面显示了适用于 Linux 和 Windows 的内置配置：

Linux

默认情况下，Ops Agent 会收集基于文件的 syslog 日志和主机指标。

如需详细了解收集的指标，请参阅接收器注入的指标。

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]

Windows

默认情况下，Ops Agent 会从 System、Application 和 Security 渠道收集 Windows 事件日志，以及主机指标、IIS 指标和 SQL Server 指标。

如需详细了解收集的指标，请参阅接收器注入的指标。

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]

日志记录配置和指标配置中更详细地讨论了这些配置。

用户指定的配置

如需替换内置配置，您需要向用户配置文件添加新配置元素。将您的 Ops Agent 配置放在以下文件中：

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

用户指定的配置将在代理重启时与内置配置合并。

如需替换内置接收器、处理器或流水线，请使用相同的标识符在 config.yaml 文件中重新定义它。从 Ops Agent 2.31.0 版开始，您还可以配置代理的日志轮换功能。如需了解详情，请参阅在 Ops Agent 中配置日志轮替。

例如，指标的内置配置包含一个指定 60 秒收集时间间隔的 hostmetrics 接收器。如需将主机指标的收集时间间隔更改为 30 秒，请在 config.yaml 文件中添加名为 hostmetrics 的指标接收器，并将 collection_interval 值设置为 30 秒，如以下示例所示：

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

如需查看更改内置配置的其他示例，请参阅日志记录配置和指标配置。您还可以停用日志记录或指标数据收集功能。日志记录 service 配置和指标 service 配置示例中说明了这些更改。

您可以使用此文件来阻止代理收集自身日志并将这些日志发送到 Cloud Logging。如需了解详情，请参阅自身日志集合。

您还可以使用此文件配置代理的日志轮换功能。如需了解详情，请参阅在 Ops Agent 中配置日志轮换。

您无法将 Ops Agent 配置为将日志或指标导出到 Cloud Logging 和 Cloud Monitoring 以外的服务。

日志记录配置

logging 配置使用之前描述的配置模型：

receivers：此元素描述要从日志文件收集的数据；此数据映射为 <timestamp, record> 模型。
processors：此可选元素描述代理如何修改收集的信息。
service：此元素将接收器和处理器连接在一起，以创建数据流，称为“流水线”。service 元素包含一个 pipelines 元素，后者可包含多个流水线定义。

每个接收器和每个处理器都可以用于多个流水线。

以下各部分分别介绍了这些元素。

Ops Agent 会将日志发送到 Cloud Logging。您无法将其配置为将日志导出到其他服务。但是，您可以将 Cloud Logging 配置为导出日志；如需了解详情，请参阅将日志路由到支持的目标位置。

日志记录接收器

receivers 元素包含一组接收器，每个接收器由 RECEIVER_ID 标识。接收器描述如何检索日志；例如，通过跟踪文件、使用 TCP 端口或者从 Windows 事件日志检索。

日志记录接收器的结构

每个接收器必须具有一个标识符 RECEIVER_ID，并包含一个 type 元素。有效类型包括：

files：通过跟踪磁盘上的文件来收集日志。
fluent_forward（Ops Agent 2.12.0 及更高版本）：收集通过 TCP Fluent Forward 协议发送的日志。
tcp（Ops Agent 2.3.0 及更高版本）：通过监听 TCP 端口来收集 JSON 格式的日志。
仅 Linux：
- syslog：收集通过 TCP 或 UDP 的 Syslog 消息。
- systemd_journald（Ops Agent 2.4.0 及更高版本）：从 systemd-journald 服务收集 systemd 日志。
仅限 Windows：
- windows_event_log：使用 Windows Event Log API 收集 Windows 事件日志。
第三方应用日志接收器

receivers 结构如下所示：

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

根据 type 元素的值，可能还有其他配置选项，如下所示：

files 接收器：
- include_paths：必填。要通过跟踪每个文件读取的文件系统路径列表。路径中可以使用通配符 (*)；例如 /var/log/*.log (Linux) 或 C:\logs\*.log (Windows)。
  
  注意：在 Windows 上指定通配符时，您必须使用 \ 作为分隔符。
  
  如需查看常见 Linux 应用日志文件的列表，请参阅常见的 Linux 日志文件。
- exclude_paths：可选。要从 include_paths 匹配的集合中排除的文件系统路径模式列表。
- record_log_file_path：可选。如果设置为 true，则从中获取日志记录的特定文件的路径将作为 agent.googleapis.com/log_file_path 标签的值显示在输出日志条目中。使用通配符时，系统只会记录从中获取记录的文件的路径。
- wildcard_refresh_interval：可选。include_paths 中通配符文件路径的刷新间隔。指定为时长，例如 30s、2m。该属性在高日志记录吞吐量下可能很有用，因为日志文件的轮替速度快于默认时间间隔。如果未指定，则默认时间间隔为 60 秒。
fluent_forward 接收器：
- listen_host：可选。要监听的 IP 地址。默认值为 127.0.0.1。
- listen_port：可选。要监听的端口。默认值为 24224。
syslog 接收器（仅适用于 Linux）：
- transport_protocol：可选。支持的值：tcp、udp默认值为 tcp。
- listen_host：可选。要监听的 IP 地址。默认值为 0.0.0.0。
- listen_port：可选。要监听的端口。默认值为 5140。
tcp 接收器：
- format：必填。日志格式。支持的值：json。
- listen_host：可选。要监听的 IP 地址。默认值为 127.0.0.1。
- listen_port：可选。要监听的端口。默认值为 5170。
windows_event_log 接收器（仅适用于 Windows）：
- channels：必填。要从中读取日志的 Windows 事件日志渠道列表。
- receiver_version：可选。控制要使用的 Windows Event Log API。支持的值包括 1 和 2。默认值为 1。
  
  注意：仅支持向后兼容版本 1。配置新的接收器时，请使用版本 2。如需从事件查看器中“应用和服务”类别下的渠道读取数据，您必须使用版本 2。
- render_as_xml：可选。如果设置为 true，则除 jsonPayload.Message 和 jsonPayload.StringInserts 之外的所有事件日志字段都呈现为名为 jsonPayload.raw_xml 的字符串字段中的 XML 文档。默认值为 false。当 receiver_version 为 1 时，无法将其设置为 true。

日志记录接收器示例

files 接收器示例：

receivers:
  RECEIVER_ID:
    type: files

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

fluent_forward 接收器示例：

注意：来自传入记录的标记保留在 LogEntry 的 logName 字段中，作为点分隔后缀 (logName = "projects/PROJECT_ID/logs/RECEIVER_ID.TAG")。

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

syslog 接收器示例（仅限 Linux）：

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

tcp 接收器示例：

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

windows_event_log 接收器示例（仅限 Windows）：

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

替换内置接收器以使用 2 版本的 windows_event_log 接收器示例：

receivers:
  windows_event_log:
    type: windows_event_log

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

systemd_journald 接收器示例：

receivers:
  RECEIVER_ID:
    type: systemd_journald

结构化负载中的特殊字段

对于可以提取结构化数据的处理器和接收器（fluent_forward 和 tcp 接收器以及 parse_json 处理器），您可以在输入中设置特殊字段，这些字段将映射到代理写入到 Logging API 的 LogEntry 对象中的特定字段。

Ops Agent 收到外部结构化日志数据时，会将顶级字段放入 LogEntry 的 jsonPayload 字段中，除非下表中列出了字段名称：

记录字段	LogEntry 字段
选项 1 `"timestamp": { "seconds": CURRENT_SECONDS, "nanos": CURRENT_NANOS, }` 选项 2 `{ "timestampSeconds": CURRENT_SECONDS, "timestampNanos": CURRENT_NANOS, }`	`timestamp`
receiver_id（不是记录字段）	`logName`
`logging.googleapis.com/httpRequest` (HttpRequest)	`httpRequest`
`logging.googleapis.com/severity`（字符串）	`severity`
`logging.googleapis.com/labels`（“字符串:字符串”结构体）	`labels`
`logging.googleapis.com/operation`（结构体）	`operation`
`logging.googleapis.com/sourceLocation`（结构体）	`sourceLocation`
`logging.googleapis.com/trace`（字符串）	`trace`
`logging.googleapis.com/spanId`（字符串）	`spanId`

任何其余的结构化记录字段仍为 jsonPayload 结构的一部分。

常见的 Linux 日志文件

下表列出了常用 Linux 应用的常见日志文件：

应用	通用日志文件
apache	如需了解 Apache 日志文件，请参阅监控第三方应用：Apache Web Server。
cassandra	如需了解 Cassandra 日志文件，请参阅监控第三方应用：Cassandra。
chef	`/var/log/chef-server/bookshelf/current /var/log/chef-server/chef-expander/current /var/log/chef-server/chef-pedant/http-traffic.log /var/log/chef-server/chef-server-webui/current /var/log/chef-server/chef-solr/current /var/log/chef-server/erchef/current /var/log/chef-server/erchef/erchef.log.1 /var/log/chef-server/nginx/access.log /var/log/chef-server/nginx/error.log /var/log/chef-server/nginx/rewrite-port-80.log /var/log/chef-server/postgresql/current`
gitlab	`/home/git/gitlab/log/application.log /home/git/gitlab/log/githost.log /home/git/gitlab/log/production.log /home/git/gitlab/log/satellites.log /home/git/gitlab/log/sidekiq.log /home/git/gitlab/log/unicorn.stderr.log /home/git/gitlab/log/unicorn.stdout.log /home/git/gitlab-shell/gitlab-shell.log`
jenkins	`/var/log/jenkins/jenkins.log`
jetty	`/var/log/jetty/out.log /var/log/jetty/.request.log /var/log/jetty/.stderrout.log`
joomla	`/var/www/joomla/logs/*.log`
magento	`/var/www/magento/var/log/exception.log /var/www/magento/var/log/system.log /var/www/magento/var/report/*`
mediawiki	`/var/log/mediawiki/*.log`
memcached	如需了解 Memcached 日志文件，请参阅监控第三方应用：Memcached。
mongodb	如需了解 MongoDB 日志文件，请参阅监控第三方应用：MongoDB。
mysql	如需了解 MySQL 日志文件，请参阅监控第三方应用：MySQL。
nginx	如需了解 nginx 日志文件，请参阅监控第三方应用：nginx。
postgres	如需了解 PostgreSQL 日志文件，请参阅监控第三方应用：PostgreSQL。
puppet	`/var/log/puppet/http.log /var/log/puppet/masterhttp.log`
puppet-enterprise	/var/log/pe-activemq/activemq.log /var/log/pe-activemq/wrapper.log /var/log/pe-console-auth/auth.log /var/log/pe-console-auth/cas_client.log /var/log/pe-console-auth/cas.log /var/log/pe-httpd/access.log /var/log/pe-httpd/error.log /var/log/pe-httpd/other_vhosts_access.log /var/log/pe-httpd/puppetdashboard.access.log /var/log/pe-httpd/puppetdashboard.error.log /var/log/pe-httpd/puppetmasteraccess.log /var/log/pe-mcollective/mcollective_audit.log /var/log/pe-mcollective/mcollective.log /var/log/pe-puppet-dashboard/certificate_manager.log /var/log/pe-puppet-dashboard/event-inspector.log /var/log/pe-puppet-dashboard/failed_reports.log /var/log/pe-puppet-dashboard/live-management.log /var/log/pe-puppet-dashboard/mcollective_client.log /var/log/pe-puppet-dashboard/production.log /var/log/pe-puppetdb/pe-puppetdb.log /var/log/pe-puppet/masterhttp.log /var/log/pe-puppet/rails.log
rabbitmq	如需了解 RabbitMQ 日志文件，请参阅监控第三方应用：RabbitMQ。
redis	如需了解 Redis 日志文件，请参阅监控第三方应用：Redis。
redmine	`/var/log/redmine/*.log`
salt	`/var/log/salt/key /var/log/salt/master /var/log/salt/minion /var/log/salt/syndic.loc`
solr	如需了解 Apache Solr 日志文件，请参阅监控第三方应用：Apache Solr。
sugarcrm	`/var/www/*/sugarcrm.log`
syslog	`/var/log/syslog /var/log/messages`
tomcat	如需了解 Apache Tomcat 日志文件，请参阅监控第三方应用：Apache Tomcat。
zookeeper	如需了解 Apache ZooKeeper 日志文件，请参阅监控第三方应用：Apache ZooKeeper。

默认注入的标签

默认情况下，日志可在 LogEntry 中包含以下标签：

字段	示例值	说明
`labels."compute.googleapis.com/resource_name"`	`test_vm`	此日志源自的虚拟机的名称。为所有日志写入。
`labels."logging.googleapis.com/instrumentation_source"`	`agent.googleapis.com/apache_access`	日志源自的接收器 `type` 的值，以 `agent.googleapis.com/` 为前缀。仅由第三方集成的接收方写入。

日志记录处理器

可选的 processors 元素包含一组处理指令，每个指令均由 PROCESSOR_ID 标识。处理器描述如何操作接收器收集的信息。

每个处理器都必须具有一个唯一标识符，并包含一个 type 元素。有效类型包括：

parse_json：解析 JSON 格式的结构化日志。
parse_multiline：解析多行日志。（仅 Linux）
parse_regex：通过正则表达式模式解析文本格式日志，将其转换为 JSON 格式的结构化日志。
exclude_logs：排除与指定规则匹配的日志（从 2.9.0 开始）。
modify_fields：在日志条目中设置/转换字段（从 2.14.0 开始）。

processors 结构如下所示：

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

根据 type 元素的值，还有其他配置选项，如下所示。

`parse_json` 处理器

配置结构

processors:
  PROCESSOR_ID:
    type: parse_json

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

parse_json 处理器将输入 JSON 解析为 LogEntry 的 jsonPayload 字段中。可以通过设置某些特殊顶级字段来解析 LogEntry 的其他部分。

time_key：可选。如果日志条目提供带有时间戳的字段，则此选项会指定该字段的名称。提取值用于设置生成的 LogEntry 的 timestamp 字段并从载荷中移除。

如果指定了 time_key 选项，您还必须指定以下内容：
- time_format：如果使用 time_key，则此选项为必填。此选项指定 time_key 字段的格式，以便系统正确识别并分析该字段。如需详细了解格式，请参阅 strptime(3) 指南。

配置示例

processors:
  PROCESSOR_ID:
    type: parse_json

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

`parse_multiline` 处理器

配置结构

processors:
  PROCESSOR_ID:
    type: parse_multiline

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

match_any：必填。一个或多个规则的列表。
- type：必填。仅支持单个值：
  - language_exceptions：允许处理器根据 language 选项的值将异常串联为一个 LogEntry。
- language：必填。仅支持单个值：
  - java：将常见的 Java 异常串联为一个 LogEntry。
  - python：将常见的 Python 异常串联为一个 LogEntry。
  - go：将常见的 Go 异常串联为一个 LogEntry。

配置示例

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]

如果您使用上述配置并有一个包含以下内容的日志文件：

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

然后，代理使用以下格式将日志注入到 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"
}

`parse_regex` 处理器

配置结构

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

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

time_key：可选。如果日志条目提供带有时间戳的字段，则此选项会指定该字段的名称。提取值用于设置生成的 LogEntry 的 timestamp 字段并从载荷中移除。

如果指定了 time_key 选项，您还必须指定以下内容：
- time_format：如果使用 time_key，则此选项为必填。此选项指定 time_key 字段的格式，以便系统正确识别并分析该字段。如需详细了解格式，请参阅 strptime(3) 指南。
regex：必填。用于解析字段的正则表达式。表达式必须包含匹配子表达式的键名称，例如 "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"。

与命名的捕获组匹配的文本将被放入 LogEntry 的 jsonPayload 字段的字段中。如需向日志添加其他结构，请使用 modify_fields 处理器。

如需了解用于从常见 Linux 应用日志文件中提取信息的一组正则表达式，请参阅常见的 Linux 日志文件。

配置示例

processors:
  PROCESSOR_ID:
    type: parse_regex

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

`exclude_logs` 处理器

配置结构：

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

此处理器的顶层配置包含一个字段 match_any，其中包含过滤条件规则列表。

match_any：必填。一个或多个规则的列表。如果某个日志条目与任何规则匹配，则 Ops Agent 不会注入该条目。

Ops Agent 注入的日志遵循 LogEntry 结构。字段名称区分大小写。您只能根据以下字段及其子字段指定规则：
- httpRequest
- jsonPayload
- labels
- operation
- severity
- sourceLocation
- trace
- spanId
以下示例规则
```
severity =~ "(DEBUG|INFO)"
```
使用正则表达式排除所有 DEBUG 和 INFO 级日志。

规则遵循 Cloud Logging 查询语言语法，但仅支持 Logging 查询语言支持的部分功能：
- 比较运算符：=、!=、:、=~、!~。仅支持字符串比较。
- 导航运算符：.。例如 jsonPayload.message。
- 布尔运算符：AND、OR、NOT。
- 使用 ( ) 对表达式进行分组。

注意：使用 exclude_logs 处理器会影响性能，因此如果您可以从来源中排除日志或可以设置排除项过滤条件，建议您避免使用此处理器。如果您需要使用 exclude_logs 处理器，我们建议您采用以下最佳实践：

最大限度地减少 exclude_logs 处理器的数量。
尽可能使用完全匹配，而不是使用正则表达式匹配。

配置示例

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

`modify_fields` 处理器

modify_fields 处理器允许自定义日志条目的结构和内容。

配置结构

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>

此处理器的顶层配置包含一个字段 fields，其中包含输出字段名称和相应转换的对应关系。对于每个输出字段，都会应用可选来源和零个或多个变更操作。

所有字段名称都使用 Cloud Logging 查询语言中的以点分隔的语法。过滤条件使用 Cloud Logging 查询语言。

所有转换都是并行应用的，这意味着来源和过滤条件对原始输入日志条目执行操作，因此不能引用同一处理器修改的任何其他字段的新值。

来源选项：最多允许一个指定来源。

未指定来源

如果未指定来源值，则目标字段中的现有值将被修改。
move_from: <source field>

<source field> 中的值将用作目标字段的来源。此外，<source field> 将从日志条目中移除。如果 move_from 和 copy_from 都引用了源字段，则源字段仍将被移除。
copy_from: <source field>

<source field> 中的值将用作目标字段的来源。除非被 move_from 操作引用或以其他方式被修改，否则 <source field> 不会从日志条目中被移除。
static_value: <string>

静态字符串 <string> 将用作目标字段的来源。

变更选项：可以将零个或多个变更运算符应用于单个字段。如果提供了多个运算符，则这些运算符将始终按以下顺序应用。

default_value: <string>

如果来源字段不存在，则输出值将设置为 <string>。如果源字段已存在（即使其中包含空字符串），则不会修改原始值。
map_values: <map>

如果输入值与 <map> 中的一个键匹配，则输出值将替换为映射中的相应值。
map_values_exclusive: {true|false}

如果 <source field> 值与 map_values 对中指定的任何键都不匹配，则当 map_values_exclusive 为 true 时，目标字段会被强制取消设置；当 map_values_exclusive 为 false，目标字段会保持不变。
type: {integer|float}

输入值将转换为整数或浮点数。如果字符串无法转换为数字，将取消设置输出值。如果字符串包含浮点数，但类型指定为 integer，则数字将被截断为整数。

请注意，Cloud Logging API 使用 JSON，因此它不支持完整的 64 位整数；如果需要 64 位（或更大）整数，则必须将其作为字符串存储在日志条目中。
omit_if: <filter>

如果过滤条件与输入日志记录匹配，将取消设置输出字段。这可用于移除占位符值，例如：
```
httpRequest.referer:
  move_from: jsonPayload.referer
  omit_if: httpRequest.referer = "-"
```

示例配置

parse_json 处理器将转换包含以下内容的 JSON 文件

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

将其转换为 LogEntry 结构，如下所示：

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

然后，可以使用 modify_fields 将其转换为此 LogEntry：

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

使用此 Ops Agent 配置：

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 = "-"
  pipelines:
    pipeline:
      receivers: [in]
      processors: [parse_json, set_http_request]

此配置从 /var/log/http.json 读取 JSON 格式的日志，并从日志中的字段填充 httpRequest 结构的一部分。

日志记录服务

日志记录服务可自定义 Ops Agent 自己的日志的详细程度，并将日志记录接收器和处理器同时连接到流水线中。service 部分包含以下元素：

log_level
pipelines

日志详细程度

log_level 字段（在 Ops Agent 2.6.0 及更高版本中提供）可自定义 Ops Agent 日志记录子模块自己的日志的详细程度。默认值为 info。可用的选项包括：error、warn、info、debug、trace。

以下配置将日志记录子模块的日志详细程度自定义为 debug：

logging:
  service:
    log_level: debug

日志记录流水线

pipelines 字段可以包含多个流水线 ID 和定义。每个 pipeline 值都由以下元素组成：

receivers：新流水线的必填参数。接收器 ID 列表，如日志记录接收器中所述。接收器 ID 在列表中的顺序无关紧要。流水线会从列出的所有接收器收集数据。
processors：可选。处理器 ID 列表，如日志记录处理器中所述。列表中处理器 ID 的顺序十分重要。每条记录会按列出的顺序通过处理器运行。

日志记录 `service` 配置示例

service 配置具有以下结构：

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

如需阻止代理收集和发送 /var/log/message 或 /var/log/syslog 条目，请重新定义默认流水线，使其包含空的 receivers 列表且没有处理器。此配置不会停止代理的日志记录子组件，因为代理必须能够收集监控子组件的日志。整个空的日志记录配置如下所示：

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

以下 service 配置定义了 ID 为 custom_pipeline 的流水线：

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

指标配置

metrics 配置使用之前描述的配置模型：

receivers：接收器定义列表。receiver 描述指标的来源；例如 cpu 或 memory 等系统指标。此列表中的接收器可以在多个流水线之间共享。
processors：处理器定义列表。processor 描述如何修改接收器收集的指标。
service：包含一个 pipelines 部分，该部分是 pipeline 定义的列表。pipeline 连接 receivers 列表和 processors 列表以形成数据流。

以下各部分分别介绍了这些元素。

Ops Agent 会将指标发送到 Cloud Monitoring。您无法将其配置为将指标导出到其他服务。

指标接收器

receivers 元素包含一组接收器定义。接收器描述从中检索指标的来源，例如 cpu 和 memory。一个接收器可以在多个流水线之间共享。

指标接收器的结构

每个接收器必须具有一个标识符 RECEIVER_ID，并包含一个 type 元素。有效的内置类型包括：

hostmetrics
iis（仅适用于 Windows）
mssql（仅适用于 Windows）

接收器还可以指定操作 collection_interval 选项。该值的格式为时长，例如 30s 或 2m。默认值为 60s。

每个接收器类型都会收集一组指标；如需了解包含的具体指标，请参阅接收器注入的指标。

每种类型只能创建一个接收器。例如，您不能定义两个类型为 hostmetrics 的接收器。

更改指标接收器中的收集时间间隔

某些关键工作负载可能需要快速提醒。通过缩短指标的收集时间间隔，您可以配置更敏感的提醒。如需了解如何评估提醒，请参阅基于指标的提醒政策的行为。

例如，以下接收器将主机指标（接收器 ID 为 hostmetrics）的收集间隔从默认的 60 秒更改为 10 秒：

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

您还可以使用相同的方法替换 Windows iis 和 mssql 指标接收器的收集时间间隔。

接收器提取的指标

Ops Agent 提取的指标具有以以下模式开头的标识符：agent.googleapis.com/GROUP。GROUP 组件标识一组相关指标；它具有 cpu、network 等值。

`hostmetrics` 接收器

hostmetrics 接收器提取以下指标组。如需了解详情，请参阅 Ops Agent 指标页面上每个组的链接部分。

组	指标
`cpu`	CPU 负载（间隔 1 分钟） CPU 负载（间隔 5 分钟） CPU 负载（间隔 15 分钟） CPU 利用率（带有 CPU 数量和 CPU 状态标签） CPU 利用率百分比（带有 CPU 数量和 CPU 状态标签）
`disk`	读取的磁盘字节数（带有设备标签）写入的磁盘字节数（带有设备标签）磁盘 I/O 时间（带有设备标签）磁盘加权 I/O 时间（带有设备标签）磁盘挂起操作次数（带有设备标签）磁盘合并操作次数（带有设备和方向标签）磁盘操作次数（带有设备和方向标签）磁盘操作时间（带有设备和方向标签）磁盘使用情况（带有设备和状态标签）磁盘利用率（带有设备和状态标签）
`gpu` 仅限 Linux；如需了解其他重要信息，请参阅 `gpu` 指标简介。	当前已使用的 GPU 内存字节数（按状态划分）进程已分配的 GPU 内存数量上限（以字节为单位）一个或多个内核在 GPU 上运行的进程生命周期中的时间百分比自上次采样以来，GPU 一直处于活跃状态的时间百分比
`interface` （仅限 Linux）	网络错误总数通过网络发送的数据包总数通过网络发送的总字节数
`memory`	内存用量（带有状态标签：已缓冲、已缓存、空闲、Slab、已使用）内存用量百分比（带有状态标签：已缓冲、已缓存、空闲、Slab、已使用）
`network`	TCP 连接计数（带有端口和 TCP 状态标签）
`swap`	交换 I/O 操作次数（带有方向标签）已使用的交换字节数（带有设备和状态标签）已使用的交换百分比（带有设备和状态标签）
`pagefile` 仅限 Windows	使用的页面文件的当前百分比（按状态）
`processes`	进程数（带有状态标签）已创建分支的进程数每进程磁盘读取 I/O（带有进程名称和其他标签）每进程磁盘写入 I/O（带有进程名称和其他标签）每进程 RSS 用量（带有进程名称和其他标签）每进程虚拟机用量（带有进程名称和其他标签）

关于 gpu 指标：

hostmetrics 接收器将 NVIDIA 管理库 (NVML) 报告的指标收集为 agent.googleapis.com/gpu 指标。

如需收集这些指标，您必须创建挂接 GPU 的虚拟机并安装 GPU 驱动程序。hostmetrics 接收器不会在没有挂接 GPU 的虚拟机上收集这些指标。

只有 Ops Agent 2.38.0 或 2.41.0 或更高版本与 GPU 监控兼容。请勿在挂接 GPU 的虚拟机上安装 Ops Agent 2.39.0 和 2.40.0 版。如需了解详情，请参阅代理崩溃和报告提及 NVIDIA。

您可以使用软件包管理器或本地安装脚本安装或升级 NVIDIA GPU 驱动程序。使用本地安装脚本时，必须先停止 Ops Agent 服务，然后才能安装驱动程序。如需停止代理，请运行以下命令：

sudo systemctl stop google-cloud-ops-agent

您还必须在安装或升级 NVIDIA GPU 驱动程序后重新启动虚拟机。

`iis` 接收器（仅限 Windows）

iis 接收器（仅限 Windows）提取 iis 组的指标。如需了解详情，请参阅代理指标页面。

组	指标
`iis` 仅限 Windows	IIS 的当前打开连接数由 IIS 传输的网络字节数 IIS 的打开连接数向 IIS 发出的请求数

`mssql` 接收器（仅限 Windows）

mssql 接收器（仅限 Windows）提取 mssql 组的指标。如需了解详情，请参阅 Ops Agent 指标页面。

组	指标
`mssql` 仅限 Windows	SQL 服务器的当前打开连接数 SQL 服务器总事务数 SQL Server 每秒写入事务数

指标处理器

processor 元素包含一组处理器定义。处理器描述要排除的接收器类型的指标。唯一支持的类型是 exclude_metrics，它使用 metrics_pattern 选项。该值是一个 glob 列表，这些 glob 与您要从接收器收集的组中排除的 Ops Agent 指标类型匹配。例如：

如需排除所有代理 CPU 指标，请指定 agent.googleapis.com/cpu/*。
如需排除代理 CPU 利用率指标，请指定 agent.googleapis.com/cpu/utilization。
如需从 Apache Cassandra 第三方集成收集的指标中排除客户端请求计数指标，请指定 workloads.googleapis.com/cassandra.client.request.count。
如需从 Apache Cassandra 第三方集成收集的指标中排除所有客户端指标，请指定 workloads.googleapis.com/cassandra.client.*。

指标处理器示例

以下示例显示了内置配置中提供的 exclude_metrics 处理器。此处理器提供空的 metrics_pattern 值，因此不排除任何指标。

processors:
  metrics_filter:
    type: exclude_metrics
    metrics_pattern: []

如需停用 Ops Agent 对所有进程指标的收集，请将以下内容添加到 config.yaml 文件中：

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

这会在 metrics_filter 处理器中从应用于 metrics 服务中默认流水线的收集中排除进程指标。

指标服务

指标服务可自定义 Ops Agent 指标模块自己的日志的详细程度，并将指标接收器和处理器同时连接到流水线中。service 部分包含两个元素：log_level 和 pipelines。

指标详细程度

log_level（在 Ops Agent 2.6.0 及更高版本中提供）可自定义 Ops Agent 指标子模块自己的日志的详细程度。默认值为 info。可用的选项包括：error、warn、info、debug。

指标流水线

service 部分只有一个元素，pipelines，其中可以包含多个流水线 ID 和定义。每个 pipeline 定义都由以下元素组成：

receivers：新流水线的必填参数。接收器 ID 列表，如指标接收器中所述。接收器 ID 在列表中的顺序无关紧要。流水线会从列出的所有接收器收集数据。
processors：可选。处理器 ID 列表，如指标处理器中所述。列表中处理器 ID 的顺序十分重要。每个指标点会按列出的顺序通过处理器运行。

指标 `service` 配置示例

service 配置具有以下结构：

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

要关闭内置指标的主机提取功能，请使用空的 receivers 列表且无处理器重新定义默认流水线。整个指标配置如下所示：

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

以下示例展示了 Windows 的内置 service 配置：

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

以下 service 配置将指标子模块的日志详细程度自定义为 debug：

metrics:
  service:
    log_level: debug

自身日志集合

默认情况下，Ops Agent 的 Fluent Bit 自身日志会发送到 Cloud Logging。这些日志可能包含大量信息，并且额外数量可能会增加 Cloud Logging 的使用费用。

从 Ops Agent 2.44.0 版开始，您可以使用 default_self_log_file_collection 选项停用这些自身日志的收集。

如需停用自日志收集，请将 global 部分添加到用户指定的配置文件，并将 default_self_log_file_collection 选项设置为值 false：

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

日志轮换配置

从 Ops Agent 2.31.0 版开始，您还可以使用配置文件设置代理的日志轮换功能。如需了解详情，请参阅在 Ops Agent 中配置日志轮换。

配置 Ops Agent

配置模型

内置配置

Linux

Windows

用户指定的配置

日志记录配置

日志记录接收器

日志记录接收器的结构

日志记录接收器示例

结构化负载中的特殊字段

常见的 Linux 日志文件

默认注入的标签

日志记录处理器

parse_json 处理器

配置结构

配置示例

parse_multiline 处理器

配置结构

配置示例

parse_regex 处理器

配置结构

配置示例

exclude_logs 处理器

配置结构：

配置示例

modify_fields 处理器

配置结构

示例配置

日志记录服务

日志详细程度

日志记录流水线

日志记录 service 配置示例

指标配置

指标接收器

指标接收器的结构

更改指标接收器中的收集时间间隔

接收器提取的指标

hostmetrics 接收器

iis 接收器（仅限 Windows）

mssql 接收器（仅限 Windows）

指标处理器

指标处理器示例

指标服务

指标详细程度

指标流水线

指标 service 配置示例

自身日志集合

日志轮换配置

`parse_json` 处理器

`parse_multiline` 处理器

`parse_regex` 处理器

`exclude_logs` 处理器

`modify_fields` 处理器

日志记录 `service` 配置示例

`hostmetrics` 接收器

`iis` 接收器（仅限 Windows）

`mssql` 接收器（仅限 Windows）

指标 `service` 配置示例