配置 Ops Agent

本文档详细介绍了 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 会从 SystemApplicationSecurity 渠道收集 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)。

      如需查看常见 Linux 应用日志文件的列表,请参阅常见的 Linux 日志文件

    • exclude_paths:可选。要从 include_paths 匹配的集合中排除的文件系统路径模式列表。

    • record_log_file_path:可选。如果设置为 true,则从中获取日志记录的特定文件的路径将作为 agent.googleapis.com/log_file_path 标签的值显示在输出日志条目中。使用通配符时,系统只会记录从中获取记录的文件的路径。

    • wildcard_refresh_interval:可选。include_paths 中通配符文件路径的刷新间隔。指定为时长,例如 30s2m。该属性在高日志记录吞吐量下可能很有用,因为日志文件的轮替速度快于默认时间间隔。如果未指定,则默认时间间隔为 60 秒。

  • fluent_forward 接收器:

    • listen_host:可选。要监听的 IP 地址。 默认值为 127.0.0.1

    • listen_port:可选。要监听的端口。 默认值为 24224

  • syslog 接收器(仅适用于 Linux):

    • transport_protocol:可选。支持的值:tcpudp默认值为 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。支持的值包括 12。 默认值为 1

    • render_as_xml:可选。如果设置为 true,则除 jsonPayload.MessagejsonPayload.StringInserts 之外的所有事件日志字段都呈现为名为 jsonPayload.raw_xml 的字符串字段中的 XML 文档。默认值为 false。 当 receiver_version1 时,无法将其设置为 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 接收器示例:

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_forwardtcp 接收器以及 parse_json 处理器),您可以在输入中设置特殊字段,这些字段将映射到代理写入到 Logging API 的 LogEntry 对象中的特定字段。

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

记录字段 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 解析为 LogEntryjsonPayload 字段中。可以通过设置某些特殊顶级字段来解析 LogEntry 的其他部分。

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

    如果指定了 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:可选。如果日志条目提供带有时间戳的字段,则此选项会指定该字段的名称。提取值用于设置生成的 LogEntrytimestamp 字段并从载荷中移除。

    如果指定了 time_key 选项,您还必须指定以下内容:

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

    与命名的捕获组匹配的文本将被放入 LogEntryjsonPayload 字段的字段中。如需向日志添加其他结构,请使用 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)"
    

    使用正则表达式排除所有 DEBUGINFO 级日志。

    规则遵循 Cloud Logging 查询语言语法,但仅支持 Logging 查询语言支持的部分功能:

    • 比较运算符:=!=:=~!~。仅支持字符串比较。
    • 导航运算符:.。例如 jsonPayload.message
    • 布尔运算符:ANDORNOT
    • 使用 ( ) 对表达式进行分组。

配置示例

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_fromcopy_from 都引用了源字段,则源字段仍将被移除。

  • copy_from: <source field>

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

  • static_value: <string>

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

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

  1. default_value: <string>

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

  2. map_values: <map>

    如果输入值与 <map> 中的一个键匹配,则输出值将替换为映射中的相应值。

  3. map_values_exclusive: {true|false}

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

  4. type: {integer|float}

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

    请注意,Cloud Logging API 使用 JSON,因此它不支持完整的 64 位整数;如果需要 64 位(或更大)整数,则必须将其作为字符串存储在日志条目中。

  5. 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。可用的选项包括:errorwarninfodebugtrace

以下配置将日志记录子模块的日志详细程度自定义为 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 描述指标的来源;例如 cpumemory 等系统指标。此列表中的接收器可以在多个流水线之间共享。
  • processors:处理器定义列表。processor 描述如何修改接收器收集的指标。
  • service:包含一个 pipelines 部分,该部分是 pipeline 定义的列表。pipeline 连接 receivers 列表和 processors 列表以形成数据流。

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

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

指标接收器

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

指标接收器的结构

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

  • hostmetrics
  • iis(仅适用于 Windows)
  • mssql(仅适用于 Windows)

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

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

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

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

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

例如,以下接收器将主机指标(接收器 ID 为 hostmetrics)的收集间隔从默认的 60 秒更改为 10 秒:

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

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

接收器提取的指标

Ops Agent 提取的指标具有以以下模式开头的标识符:agent.googleapis.com/GROUPGROUP 组件标识一组相关指标;它具有 cpunetwork 等值。

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 用量(带有进程名称和其他标签)
每进程虚拟机用量(带有进程名称和其他标签)
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 指标类型匹配。例如:

指标处理器示例

以下示例显示了内置配置中提供的 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_levelpipelines

指标详细程度

log_level(在 Ops Agent 2.6.0 及更高版本中提供)可自定义 Ops Agent 指标子模块自己的日志的详细程度。默认值为 info。可用的选项包括:errorwarninfodebug

指标流水线

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 中配置日志轮换