設定作業套件代理程式

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

• 變更 Ops Agent 的設定，以達成下列目標：

  • 關閉內建記錄或指標擷取功能。

    • 如要關閉記錄擷取功能，請參閱記錄設定範例service。

    • 如要關閉主機指標擷取功能，請參閱指標設定範例service。

  • 自訂代理程式收集記錄的記錄檔檔案路徑；請參閱記錄接收器。

  • 自訂代理程式用來處理記錄項目的結構化記錄格式，方法是剖析 JSON 或使用規則運算式；請參閱「記錄處理器」。

  • 變更指標的取樣率；請參閱「指標接收器」。

  • 自訂要啟用哪些指標群組。根據預設，代理程式會收集所有系統指標，例如 cpu 和 memory；詳情請參閱「指標處理器」。

  • 自訂代理程式輪替記錄的方式，請參閱「記錄輪替設定」。

  • 從支援的第三方應用程式收集指標和記錄檔。 如需支援的應用程式清單，請參閱「監控第三方應用程式」。

  • 使用 Prometheus 接收器收集自訂指標。

  • 使用 OpenTelemetry Protocol (OTLP) 接收器收集自訂指標和追蹤記錄。

• 您想瞭解作業套件代理程式設定的技術詳細資料。

設定模型

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

設定的構成要素如下：

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

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

內建設定

Ops Agent 的內建設定會定義記錄和指標的預設收集作業。以下顯示 Linux 和 Windows 的內建設定：

logging:
  receivers:
    syslog:
      type: files
      include_paths:
      - /var/log/messages
      - /var/log/syslog
  service:
    pipelines:
      default_pipeline:
        receivers: [syslog]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics]
        processors: [metrics_filter]

logging:
  receivers:
    windows_event_log:
      type: windows_event_log
      channels: [System, Application, Security]
  service:
    pipelines:
      default_pipeline:
        receivers: [windows_event_log]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
    iis:
      type: iis
      collection_interval: 60s
    mssql:
      type: mssql
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics, iis, mssql]
        processors: [metrics_filter]

如要進一步瞭解這些設定，請參閱「記錄設定」和「指標設定」。

使用者指定的設定

如要覆寫內建設定，請在使用者設定檔中新增設定元素。將 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：這個元素說明要從記錄檔收集的資料；這項資料會對應至 <時間戳記、記錄> 模型。
• 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 事件記錄 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

    如需常見的 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。

  • 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 接收器範例：

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)：windows_event_log

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 欄位，但欄位名稱列於下表時除外：

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

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

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

常見的 Linux 記錄檔

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

預設擷取的標籤

根據預設，記錄檔可在 LogEntry 中包含下列標籤：

記錄處理器

選用的 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 欄位。如要剖析