Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定作業套件代理程式

自訂 Ops Agent 設定，即可控管代理程式如何收集、剖析及轉送 Compute Engine 執行個體的記錄、指標和追蹤記錄。雖然 Ops Agent 內建常見系統記錄和主機指標的預設設定，但您可以定義自訂覆寫設定，根據工作負載調整遙測資料收集作業。

常見設定工作

您可以修改 Ops Agent 的設定，以達成下列目標：

關閉內建記錄或指標擷取功能：
- 如要關閉記錄擷取功能，請參閱「service 設定範例」。
- 如要關閉主機指標擷取功能，請參閱「指標service設定範例」。
自訂代理程式收集記錄的記錄檔路徑，請參閱「記錄接收器」。
剖析 JSON 或使用規則運算式，自訂代理程式用來處理記錄項目的結構化記錄格式；請參閱「Logging 處理器」。
變更指標的取樣率；請參閱「指標接收器」。
自訂要啟用的指標群組。根據預設，代理程式會收集所有系統指標，例如 cpu 和 memory；請參閱「指標處理器」。
自訂代理程式輪替記錄的方式；請參閱「記錄輪替設定」。
從支援的第三方應用程式收集指標和記錄檔。如需支援的應用程式清單，請參閱「監控第三方應用程式」。
使用 Prometheus 接收器收集自訂指標。
使用 OpenTelemetry Protocol (OTLP) 接收器收集自訂指標和追蹤記錄。

設定模型

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 檔案中重新定義，並使用相同的 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 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 事件記錄擷取。

記錄接收器的結構

每個接收器都必須有 ID 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：必填，要透過追蹤每個檔案來讀取的檔案系統路徑清單。路徑中可使用下列萬用字元：
  - *：比對單一目錄或檔案名稱中，任何非路徑分隔字元的序列。
    - 範例 (Linux)：/var/log/*.log 會比對直接位於 /var/log/ 中所有結尾為 .log 的檔案。
    - 範例 (Linux)：/var/log/app_*/server.log 符合 /var/log/app_1/server.log 和 /var/log/app_2/server.log，但「不」符合 /var/log/app_1/v2/server.log。
  - ** (globstar)：比對路徑中的零或多個目錄。這個模式用於比對多個目錄層級的檔案 (遞迴)。
    - 範例 (Linux)：/var/log/**/*.log 會比對 /var/log 中任何以 .log 結尾的檔案，或任何深度的子目錄 (例如 /var/log/app1.log、/var/log/apache2/access.log)。
    - 範例 (Linux)：如要從建立版本化或執行個體專屬子目錄 (例如 /opt/my-app/logs/instance-01/app.log、/opt/my-app/logs/groupA/instance-02/app.log) 的應用程式執行個體收集記錄，可以使用 globstar：/opt/my-app/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 中萬用字元檔案路徑的重新整理間隔。以時間長度表示，例如 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]

覆寫內建接收器以使用 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` (struct of string:string)	`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」。
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`
鹽	`/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 就不會擷取該項目。

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 = "-"
  service:
    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

Logging 管道

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。多個管道可共用同一個接收器。

指標接收器的結構

每個接收器都必須有 ID RECEIVER_ID，並包含 type 元素。有效的內建類型如下：

hostmetrics
iis (僅限 Windows)
mssql (僅限 Windows)

接收器也可以指定作業 collection_interval 選項。值的格式為時間長度，例如 30s 或 2m。預設值為 60s。

每種接收器類型都會收集一組指標。如要瞭解包含的特定指標，請參閱「接收器擷取的指標」。

變更指標接收器的收集間隔

某些重要工作負載可能需要快速發出警告。縮短指標的收集間隔，即可設定更靈敏的警告。如要瞭解快訊的評估方式，請參閱「以指標為基準的警告政策行為」。

舉例來說，下列接收器會將主機指標的收集間隔 (接收器 ID 為 hostmetrics) 從預設的 60 秒變更為 10 秒：

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

注意：這項覆寫作業之所以有效，是因為接收器 ID hostmetrics 與內建設定中的接收器 ID 相同。凡是使用 hostmetrics 接收器的管道，現在都會使用這項覆寫設定。

您也可以使用相同技術，覆寫 Windows iis 和 mssql 指標接收器的收集間隔。

接收器擷取的指標

Ops Agent 擷取的指標 ID 開頭為下列模式：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`	記憶體用量，並標示狀態 (buffered、cached、free、slab、used) 記憶體用量百分比，並標示狀態 (buffered、cached、free、slab、used)
`network`	TCP 連線數量，並附上通訊埠和 TCP 狀態標籤
`swap`	Swap I/O 作業，並加上方向標籤 Swap 已用位元組，並加上裝置和狀態標籤 Swap 已用百分比，並加上裝置和狀態標籤
`pagefile` 僅限 Windows	目前各狀態使用的分頁檔百分比
`processes`	程序數量，標籤為狀態分支程序數量個別程序的磁碟讀取 I/O，標籤為程序名稱和其他資訊個別程序的磁碟寫入 I/O，標籤為程序名稱和其他資訊個別程序的 RSS 用量，標籤為程序名稱和其他資訊個別程序的 VM 用量，標籤為程序名稱和其他資訊

關於gpu指標：

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

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

只有 Ops Agent 2.38.0 版或 2.41.0 以上版本與 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 伺服器連線數 SQL 伺服器每秒交易總數 SQL 伺服器每秒寫入交易數

指標處理器

processor 元素包含一組處理器定義。處理器會說明要排除的接收器類型指標。唯一支援的類型是 exclude_metrics，可接受 metrics_pattern 選項。這個值是一份 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 服務中套用至預設管道的 metrics_filter 處理器，就不會收集程序指標。

指標服務

指標服務會自訂 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 中設定記錄輪替」。

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

常見設定工作

設定模型

內建設定

Linux

Windows

使用者指定的設定

記錄設定

記錄接收器

記錄接收器的結構

記錄接收器範例

結構化酬載中的特殊欄位

常見的 Linux 記錄檔

預設擷取的標籤

記錄處理器

parse_json 處理器

設定結構

範例設定

parse_multiline 處理器

設定結構

範例設定

parse_regex 處理器

設定結構

範例設定

exclude_logs 處理器

設定結構：

範例設定

modify_fields處理器

設定結構

設定範例

記錄服務

記錄詳細程度

Logging 管道

service 記錄設定範例

指標設定

指標接收器

指標接收器的結構

變更指標接收器的收集間隔

接收器擷取的指標

hostmetrics 接收器

iis 接收器 (僅限 Windows)

mssql 接收器 (僅限 Windows)

指標處理器

範例指標處理器

指標服務

指標詳細程度

指標管道

指標 service 設定範例

收集自我記錄

記錄輪替設定

設定作業套件代理程式

`parse_json` 處理器

`parse_multiline` 處理器

`parse_regex` 處理器

`exclude_logs` 處理器

`modify_fields`處理器

`service` 記錄設定範例

`hostmetrics` 接收器

`iis` 接收器 (僅限 Windows)

`mssql` 接收器 (僅限 Windows)

指標 `service` 設定範例