本頁面由 Cloud Translation API 翻譯而成。

設定作業套件代理程式

本文詳細說明作業套件代理程式的預設和自訂設定。如有下列任一情況，請詳閱本文：

變更 Ops Agent 的設定，以達成下列目標：
- 關閉內建的記錄或指標擷取功能。
  - 如要關閉記錄擷取功能，請參閱記錄設定範例。service
  - 如要關閉主機指標擷取功能，請參閱指標設定範例service。
- 自訂代理程式收集記錄的記錄檔檔案路徑；請參閱記錄接收器。
- 透過剖析 JSON 或使用規則運算式，自訂代理程式用來處理記錄項目的結構化記錄格式；請參閱「記錄處理器」。
- 變更指標的取樣率；請參閱「指標接收器」。
- 自訂要啟用哪些指標群組。根據預設，代理程式會收集所有系統指標，例如 cpu 和 memory；詳情請參閱「指標處理器」。
- 自訂代理程式輪替記錄的方式，請參閱「記錄輪替設定」。
- 從支援的第三方應用程式收集指標和記錄檔。如需支援的應用程式清單，請參閱「監控第三方應用程式」。
- 使用 Prometheus 接收器收集自訂指標。
- 使用 OpenTelemetry Protocol (OTLP) 接收器收集自訂指標和追蹤記錄。
您想瞭解作業套件代理程式設定的技術詳細資料。

設定模型

作業套件代理程式會使用內建的預設設定，您無法直接修改這項內建設定。而是建立覆寫檔案，代理程式重新啟動時，系統會將這些檔案與內建設定合併。

設定的建構區塊如下：

receivers：這個元素說明代理程式收集的內容。
processors：這個元素說明代理程式如何修改收集到的資訊。
service：這個元素會將接收器和處理器連結在一起，建立資料流程，稱為「管道」。service 元素包含 pipelines 元素，而該元素可包含多個管道。

內建設定是由這些元素組成，您可以使用相同元素覆寫內建設定。

內建設定

作業套件代理程式的內建設定會定義記錄和指標的預設收集作業。以下顯示 Linux 和 Windows 的內建設定：

Linux

根據預設，作業套件代理程式會收集以檔案為基礎的 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

根據預設，作業套件代理程式會從 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 檔案中重新定義，並宣告相同的 ID。從 Ops Agent 2.31.0 版開始，您也可以設定代理程式的記錄檔輪替功能；詳情請參閱「在 Ops Agent 中設定記錄檔輪替」。

舉例來說，指標的內建設定包含 hostmetrics 接收器，指定 60 秒的收集間隔。如要將主機指標的收集間隔變更為 30 秒，請在 config.yaml 檔案中加入名為 hostmetrics 的指標接收器，將 collection_interval 值設為 30 秒，如下列範例所示：

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

如需變更內建設定的其他範例，請參閱「記錄設定」和「指標設定」。您也可以關閉記錄或指標資料的收集功能。這些變更說明請參閱「記錄 service 設定」和「指標 service 設定」範例。

您可以使用這個檔案，防止代理程式收集自我記錄，並將這些記錄傳送至 Cloud Logging。詳情請參閱「收集自我記錄」。

您也可以使用這個檔案設定代理程式的記錄檔輪替功能；詳情請參閱「在 Ops 代理程式中設定記錄檔輪替」。

您無法將作業套件代理程式設定為將記錄檔或指標匯出至 Cloud Logging 和 Cloud Monitoring 以外的服務。

記錄設定

logging 設定會使用先前說明的設定模型：

receivers：這個元素說明要從記錄檔收集的資料；這項資料會對應至 <時間戳記、記錄> 模型。
processors：這個選用元素說明代理程式如何修改收集到的資訊。
service：這個元素會將接收器和處理器連結在一起，建立資料流程，稱為「管道」。service 元素包含 pipelines 元素，其中可包含多個管道定義。

每個接收器和處理器都可用於多個管道。

以下各節將說明這些元素。

作業套件代理程式會將記錄檔傳送至 Cloud Logging。您無法設定將記錄檔匯出至其他服務。不過，您可以設定 Cloud Logging 匯出記錄，詳情請參閱「將記錄轉送至支援的目的地」。

記錄接收器

receivers 元素包含一組接收器，每個接收器都由 RECEIVER_ID 識別。接收器說明如何擷取記錄，例如透過追蹤檔案、使用 TCP 連接埠或從 Windows 事件記錄檔擷取。

記錄接收端的結構

每個接收器都必須有 ID (RECEIVER_ID)，並包含 type 元素。有效類型包括：

files：透過追蹤磁碟上的檔案來收集記錄。
fluent_forward (作業套件代理程式 2.12.0 以上版本)：收集透過 TCP 傳送的 Fluent Forward 通訊協定記錄。
tcp (作業套件代理程式 2.3.0 以上版本)：監聽 TCP 連接埠，以 JSON 格式收集記錄。
僅適用於 Linux：
- syslog：透過 TCP 或 UDP 收集 Syslog 訊息。
- systemd_journald (作業套件代理程式 2.4.0 以上版本)：從 systemd-journald 服務收集 systemd 日誌記錄。
僅限 Windows：
- windows_event_log：使用 Windows 事件記錄 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。
- listen_host：要接聽的 IP 位址。
- listen_port：要接聽的通訊埠。
tcp 接收器：
- format：必填。記錄格式。支援的值：json。
- listen_host：選用。要接聽的 IP 位址。預設值為 127.0.0.1。
- listen_port：選用。要監聽的通訊埠。預設值為 5170。
windows_event_log 接收器 (僅限 Windows)：
- channels：必填。要從中讀取記錄的 Windows 事件記錄通道清單。
- receiver_version：選用。控制要使用的 Windows 事件記錄 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]

範例 windows_event_log 接收器會覆寫內建接收器，改用版本 2：

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` (struct)	`operation`
`logging.googleapis.com/sourceLocation` (struct)	`sourceLocation`
`logging.googleapis.com/trace` (字串)	`trace`
`logging.googleapis.com/spanId` (字串)	`spanId`

其餘結構化記錄欄位仍屬於 jsonPayload 結構。

常見的 Linux 記錄檔

下表列出常用 Linux 應用程式的常見記錄檔：

應用程式	常見記錄檔
Apache	如要瞭解 Apache 記錄檔，請參閱「監控第三方應用程式：Apache 網路伺服器」。
cassandra	如要瞭解 Cassandra 記錄檔，請參閱監控第三方應用程式：Cassandra。
廚師	`/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`
鹽	`/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 識別。處理器說明如何操控接收器收集的資訊。

每個處理器都必須有專屬 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]

在 extract_structure 處理器中，field: message 陳述式表示規則運算式會套用至記錄檔項目的 jsonPayload.message 欄位。根據預設，檔案接收器會將記錄檔的每一行放入記錄項目，並使用名為 jsonPayload.message 的單一酬載欄位。

extract_structure 處理器會將擷取的欄位放入 LogEntry.jsonPayload 欄位的子欄位中。YAML 檔案中的其他陳述式會導致兩個擷取的欄位 (time 和 severity) 遭到移動。time_key: time 陳述式會提取 LogEntry.jsonPayload.time 欄位、剖析時間戳記，然後新增 LogEntry.timestamp 欄位。move_severity 處理器會將嚴重程度欄位從 LogEntry.jsonPayload.severity 欄位移至 LogEntry.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 就不會擷取該項目。

作業套件代理程式擷取的記錄檔會遵循 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> 的值做為目標欄位的來源。除非 <source field> 也由 move_from 作業參照，或以其他方式修改，否則不會從記錄項目中移除。
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",
  }
}

使用這項作業套件代理程式設定：

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]

這項設定會從 /var/log/http.json 讀取 JSON 格式的記錄，並從記錄中的欄位填入 httpRequest 結構的部分內容。

記錄服務

記錄服務會自訂作業套件代理程式記錄的詳細程度，並將記錄接收器和處理器連結到管道。service 區段包含下列元素：

log_level
pipelines

記錄詳細程度

log_level 欄位適用於 2.6.0 以上版本的作業套件代理程式，可自訂作業套件代理程式記錄子模組自有記錄的詳細程度。預設值為 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 清單，形成資料流程。

以下各節將說明這些元素。

作業套件代理程式會將指標傳送至 Cloud Monitoring。您無法設定將指標匯出至其他服務。

指標接收器

receivers 元素包含一組接收器定義。接收器會說明要從何處擷取指標，例如 cpu 和 memory。多個管道可以共用接收器。

指標接收端的結構

每個接收器都必須有 ID (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 指標接收器的收集間隔。

接收器擷取的指標

作業套件代理程式擷取的指標，其 ID 開頭會符合下列模式：agent.googleapis.com/GROUP。GROUP 元件會識別一組相關指標，其值包括 cpu、network 等。

`hostmetrics`接收器

hostmetrics 接收器會擷取下列指標群組。詳情請參閱「Ops Agent 指標」頁面中各群組的連結部分。

群組	指標
`cpu`	每 1 分鐘的 CPU 負載每 5 分鐘的 CPU 負載每 15 分鐘的 CPU 負載 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 用量，附有程序名稱和其他標籤每個程序的 VM 用量，附有程序名稱和其他標籤

關於 gpu 指標：

hostmetrics 接收器會收集 NVIDIA 管理程式庫 (NVML) 回報的指標，做為 agent.googleapis.com/gpu 指標。

如要收集這些指標，請建立連接 GPU 的 VM，並安裝 GPU 驅動程式。如果 VM 未連接 GPU，hostmetrics 接收器不會收集這些指標。

只有 2.38.0 版或 2.41.0 以上版本的 Ops Agent 才能監控 GPU。請勿在已連接 GPU 的 VM 上安裝 Ops Agent 2.39.0 和 2.40.0 版。詳情請參閱「代理程式當機，且報告提及 NVIDIA」。

您可以使用套件管理員或本機安裝指令碼，安裝或升級 NVIDIA GPU 驅動程式。使用本機安裝指令碼時，必須先停止 Ops Agent 服務，才能繼續安裝驅動程式。如要停止代理程式，請執行下列指令：

sudo systemctl stop google-cloud-ops-agent

安裝或升級 NVIDIA GPU 驅動程式後，也必須重新啟動 VM。

`iis` 接收器 (僅限 Windows)

iis 接收器 (僅限 Windows) 會擷取 iis 群組的指標。詳情請參閱「代理程式指標」頁面。

群組	指標
`iis` 僅適用於 Windows	目前開啟的 IIS 連線 IIS 傳輸的網路位元組開啟的 IIS 連線向 IIS 發出的要求

`mssql` 接收器 (僅限 Windows)

mssql 接收器 (僅限 Windows) 會擷取 mssql 群組的指標。詳情請參閱「Ops Agent 指標」頁面。

群組	指標
`mssql` 僅適用於 Windows	目前開啟的 SQL Server 連線 SQL Server 每秒交易總數 SQL Server 每秒寫入交易數

指標處理器

processor 元素包含一組處理器定義。處理器會說明要排除的接收器類型指標。唯一支援的類型是 exclude_metrics，其中會採用 metrics_pattern 選項。這個值是與作業代理程式指標類型相符的 glob 清單，您要從接收器收集的群組中排除這些類型。例如：

如要排除所有代理程式 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: []

如要停用作業套件代理程式收集所有程序指標，請在 config.yaml 檔案中新增下列內容：

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

這會排除 metrics 服務中預設管道適用的處理器中的程序指標收集作業。metrics_filter

指標服務

指標服務會自訂作業套件代理程式指標模組本身記錄的詳細程度，並將指標接收器和處理器連結至管道。service 區段有兩個元素：log_level 和 pipelines。

指標詳細程度

log_level (適用於 2.6.0 以上版本的作業套件代理程式) 可自訂作業套件代理程式指標子模組的記錄詳細程度。預設值為 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 中設定記錄檔輪替」。

設定作業套件代理程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

設定模型

內建設定

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`