設定 Logging 代理程式

本頁面詳細說明 Cloud Logging 代理程式的預設和自訂設定。

大多數使用者不需要閱讀本頁。除非您有意：

• 想瞭解 Cloud Logging 代理程式設定的深入技術詳細資料。

• 您想變更 Cloud Logging 代理程式的設定。

預設設定

Logging 代理程式 google-fluentd 是 fluentd 記錄資料收集器的修改版本。記錄代理程式會提供預設設定；在大多數情況下，您不需要額外設定。

在預設設定中，記錄代理程式會將記錄檔串流至 Cloud Logging，這些記錄檔包含在預設記錄檔清單中。您可以設定代理程式串流傳輸其他記錄檔。詳情請參閱本頁的「自訂 Logging 代理程式設定」。

Logging 代理程式會使用 fluentd 輸入外掛程式，從外部來源 (例如磁碟上的檔案) 擷取及提取事件記錄，或剖析收到的記錄檔記錄。輸入外掛程式會與代理程式一起提供，也可以做為 Ruby Gem 個別安裝；請查看內含外掛程式清單。

代理程式會透過 fluentd 內建的 in_tail 外掛程式，讀取 VM 執行個體記錄檔中儲存的記錄檔記錄。每筆記錄檔記錄都會轉換為 Cloud Logging 的 記錄項目結構。每個記錄的內容大多會記錄在記錄項目的酬載中，但記錄項目也包含時間戳記和嚴重性等標準元素。記錄代理程式要求每個記錄記錄都必須加上字串格式標記；所有查詢和輸出外掛程式都會與特定一組標記相符。記錄名稱通常會採用 projects/[PROJECT-ID]/logs/[TAG] 格式。例如，這個記錄名稱包含標記 structured-log：

projects/my-sample-project-12345/logs/structured-log

輸出外掛程式會將每則內部化結構化訊息轉換為 Cloud Logging 中的記錄項目。酬載則變為文字或 JSON 酬載。

此頁面的以下章節會詳細討論預設設定。

預設設定定義

下列章節會說明 syslog 的預設設定定義、轉送輸入外掛程式、第三方應用程式記錄檔的輸入設定 (例如預設記錄檔清單所列項目)，以及我們的 Google Cloud fluentd 輸出外掛程式。

根設定檔位置

• Linux：/etc/google-fluentd/google-fluentd.conf

  這個根設定檔也會匯入 /etc/google-fluentd/config.d 資料夾中的所有設定檔。

• Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

  如果您執行的 Logging 代理程式是 v1-5 之前的版本，位置為：C:\GoogleStackdriverLoggingAgent\fluent.conf

Syslog 設定

• 設定檔位置：/etc/google-fluentd/config.d/syslog.conf

• 說明：此檔案內的設定會將 syslog 設為記錄檔輸入來源。

• 查看設定存放區。

in_forward 輸入外掛程式設定

• 設定檔位置：/etc/google-fluentd/config.d/forward.conf

• 說明：這個檔案包含 in_forward fluentd 輸入外掛程式的設定。in_forward 輸入外掛程式可讓您透過 TCP 通訊端傳入記錄檔。

• 請參閱此外掛程式和設定存放區的詳細 fluentd 說明文件。

第三方應用程式記錄檔輸入設定

• 設定檔位置： /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

• 說明：此目錄內的設定檔會指定第三方應用程式記錄檔做為記錄檔輸入來源。除了 syslog.conf 和 forward.conf 之外，每個檔案皆代表一個應用程式 (例如，apache.conf 代表 Apache 應用程式)。

• 查看設定存放區。

¹ 如果您使用 <parse> 節，請使用 @type 指定記錄格式。

Google Cloud fluentd 輸出外掛程式設定

• 設定檔位置：

  • Linux：/etc/google-fluentd/google-fluentd.conf

  • Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    如果您執行的 Logging 代理程式是 v1-5 之前的版本，位置為：C:\GoogleStackdriverLoggingAgent\fluent.conf

• 說明：這個檔案內的設定選項會控制Google Cloud fluentd 輸出外掛程式的行為。

• 前往設定存放區。

監控功能設定

輸出外掛程式遙測

enable_monitoring 選項可控制 Google Cloud fluentd 輸出外掛程式是否收集內部追蹤資料。設定為 true 時，Logging 代理程式會追蹤要求傳送至 Cloud Logging 的記錄項目數量，以及 Cloud Logging 成功擷取的記錄項目實際數量。如果設為 false，輸出外掛程式就不會收集任何指標。

monitoring_type 選項會控制代理程式如何公開這項遙測資料。請參閱以下指標清單。

設定為 prometheus 時，Logging 代理程式會在 Prometheus 端點上公開 Prometheus 格式指標 (預設為 localhost:24231/metrics；如需進一步瞭解如何自訂，請參閱 prometheus 和 prometheus_monitor 外掛程式設定)。在 Compute Engine VM 上，您必須安裝並執行監控代理程式，才能將這些指標寫入 Monitoring API。

設定為 opencensus (v1.6.25 起的預設值) 時，Logging 代理程式會直接將自己的健康指標寫入 Monitoring API。為此，您必須將 roles/monitoring.metricWriter 角色授予 Compute Engine 預設服務帳戶，即使未安裝監控代理程式也一樣。

在 opencensus 模式中，Monitoring 代理程式和 Logging 代理程式會將下列指標寫入 Monitoring API：

• agent.googleapis.com/agent/uptime (標示為 version)：記錄代理程式的正常運作時間。
• agent.googleapis.com/agent/log_entry_count 和 response_code 標籤：記錄代理程式寫入的記錄項目數量。
• agent.googleapis.com/agent/log_entry_retry_count (附有 response_code 標籤)：記錄代理程式寫入的記錄項目數量。
• agent.googleapis.com/agent/request_count (帶有 response_code 標籤)：Logging 代理程式發出的 API 要求數量。

如要進一步瞭解這些指標，請參閱「代理程式指標」頁面。

此外，輸出外掛程式會在 prometheus 模式中公開下列 Prometheus 指標：

• uptime (標示為 version)：記錄代理程式的正常運作時間。
• stackdriver_successful_requests_count 與 grpc 和 code 標籤： Logging API 成功要求的數量。
• stackdriver_failed_requests_count 與 grpc 和 code 標籤：Logging API 失敗要求的數量，依錯誤代碼細分。
• stackdriver_ingested_entries_count (含 grpc 和 code 標籤)：Logging API 擷取的記錄項目數量。
• stackdriver_dropped_entries_count (含 grpc 和 code 標籤)：Logging API 拒絕的記錄項目數量。
• stackdriver_retried_entries_count (含 grpc 和 code 標籤)：因發生暫時性錯誤，導致 Google Cloud fluentd 輸出外掛程式無法擷取的記錄項目數量，並已重試。

prometheus 和 prometheus_monitor 外掛程式設定

• 設定檔位置： /etc/google-fluentd/google-fluentd.conf

• 說明：這個檔案內的設定選項會控制 prometheus 和 prometheus_monitor 外掛程式的行為。prometheus_monitor 外掛程式可監控 Fluentd 的核心基礎架構。prometheus 外掛程式會透過本機通訊埠以 Prometheus 格式公開指標，包括 prometheus_monitor 外掛程式和上述 google_cloud 外掛程式提供的指標。詳情請參閱 https://docs.fluentd.org/deployment/monitoring-prometheus。

• 前往設定存放區。

針對 Fluentd 監控，預設會啟用內建的 Prometheus http 指標伺服器。您可以從設定中移除下列部分，停止啟動這個端點：

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

處理酬載

預設設定下，記錄代理程式支援的大部分記錄檔都來自記錄檔的檔案，且會以記錄項目內未結構化 (文字) 的酬載形式擷取。

唯一的例外是 in_forward 輸入外掛程式。這個外掛程式預設為啟用，只接受結構化記錄檔，且會將記錄檔擷取為記錄項目的結構化 (JSON) 酬載。詳情請參閱本頁的「透過 in_forward 外掛程式串流結構化 (JSON) 記錄檔」一文。

當記錄檔記錄為序列化 JSON 物件，且 detect_json 選項為啟用，輸出外掛程式會將記錄檔項目轉換為結構化的 (JSON) 酬載。在 App EngineVM 彈性環境與 Google Kubernetes Engine 執行的 VM 執行個體中，此選項預設為啟用。在 App Engine 標準環境中執行的 VM 執行個體中，這個選項預設為停用。啟用 detect_json 選項後，剖析的任何 JSON 一律會以 jsonPayload 形式攝入。

您可自訂代理程式的設定，使其支援從其他資源擷取結構化記錄檔。詳情請參閱「將結構化 (JSON) 記錄記錄串流傳送至 Cloud Logging」一文。

由自訂設定的記錄代理程式串流傳送的記錄檔酬載，可以是單一非結構化文字訊息 (textPayload)，或結構化 JSON 訊息 (jsonPayload)。

結構化酬載中的特殊欄位

當記錄代理程式收到結構化記錄記錄時，會將任何與下表相符的鍵移至 LogEntry 物件中的對應欄位。否則，金鑰會成為 LogEntry.jsonPayload 欄位的一部分。這項行為可讓您在 LogEntry 物件中設定特定欄位，這些欄位會寫入 Logging API。舉例來說，如果結構化記錄記錄包含 severity 的鍵，則記錄代理程式會填入 LogEntry.severity 欄位。

時間相關欄位

一般來說，記錄項目的時間相關資訊會儲存在 LogEntry 物件的 timestamp 欄位中：

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

如果記錄項目的來源是結構化資料，記錄代理程式會使用下列規則，在 jsonPayload 項目中搜尋與時間相關的資訊：

1. 搜尋 timestamp 欄位，這是 JSON 物件，其中包含 seconds 和 nanos 欄位，分別代表從世界標準時間紀元後帶正負號的秒數，以及非負數小數秒數：

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

2. 如果先前的搜尋作業失敗，請搜尋一組 timestampSeconds 和 timestampNanos 欄位：

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

3. 如果上一個搜尋作業失敗，請搜尋 time 欄位，該欄位為 RFC 3339 格式的字串：

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

找到時間相關資訊後，記錄代理程式會使用該資訊設定 LogEntry.timestamp 的值，但不會將該資訊從結構化記錄複製到 LogEntry.jsonPayload 物件。

系統會將未用於設定 LogEntry.timestamp 欄位值的時間相關欄位，從結構化記錄複製到 LogEntry.jsonPayload 物件。舉例來說，如果結構化記錄包含 timestamp JSON 物件和 time 欄位，則系統會使用 timestamp JSON 物件中的資料來設定 LogEntry.timestamp 欄位。LogEntry.jsonPayload 物件包含 time 欄位，因為這個欄位並未用於設定 LogEntry.timestamp 值。

自訂代理程式設定

依據預設，記錄代理程式本身會串流預設記錄檔清單；但您也可以自訂記錄代理程式，將其他記錄檔傳送至 Logging，或新增輸入設定來調整代理程式設定。

這些章節中的設定定義只適用於 fluent-plugin-google-cloud 輸出外掛程式，並指定將記錄檔轉換並擷取到 Cloud Logging 的方式。

• 主設定檔位置：

  • Linux：/etc/google-fluentd/google-fluentd.conf

  • Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    如果您執行的 Logging 代理程式是 v1-5 之前的版本，位置為：C:\GoogleStackdriverLoggingAgent\fluent.conf

• 說明：這個檔案內的設定選項會控制 fluent-plugin-google-cloud 輸出外掛程式的行為。

• 查看設定存放區。

串流來自其他輸入內容的記錄檔

您可以自訂記錄代理程式，新增輸入設定，以便傳送其他記錄至 Logging。

透過記錄檔串流未結構化 (文字) 記錄檔

1. 透過 Linux 指令提示建立記錄檔：

   touch /tmp/test-unstructured-log.log
   

2. 在額外設定目錄 /etc/google-fluentd/config.d 中建立名為 test-unstructured-log.conf 的新設定檔：

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # The path of the log file.
       path /tmp/test-unstructured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag unstructured-log
   </source>
   EOF
   

   除了建立新檔案，您也可以將設定資訊新增至現有設定檔。

3. 重新啟動代理程式，以套用設定變更：

   sudo service google-fluentd restart
   

4. 在記錄檔中產生記錄檔的記錄：

   echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
   

5. 查看 Logs Explorer，檢視所擷取的記錄項目：

   {
     insertId:  "eps2n7g1hq99qp"
     labels: {
     compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/unstructured-log"
     receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
     resource: {
     labels: {
       instance_id:  "3914079432219560274"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     textPayload:  "This is a log from the log file at test-unstructured-log.log"
     timestamp:  "2018-03-21T01:47:05.051902169Z"
   }
   

透過記錄檔的檔案串流結構化 (JSON) 記錄檔

您可以設定 Logging 代理程式，要求每個記錄項目都必須將特定記錄輸入內容結構化。您也可以自訂 Logging 代理程式，從記錄檔擷取 JSON 格式的內容。當代理程式已設定為擷取 JSON 內容時，輸入內容必須採用適當格式，讓每個 JSON 物件都位於新行中：

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

如要設定記錄代理程式以擷取 JSON 格式內容，請執行下列操作：

1. 透過 Linux 指令提示建立記錄檔：

   touch /tmp/test-structured-log.log
   

2. 在額外設定目錄 /etc/google-fluentd/config.d 中建立名為 test-structured-log.conf 的新設定檔：

   sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'json' indicates the log is structured (JSON).
           @type json
       </parse>
       # The path of the log file.
       path /tmp/test-structured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag structured-log
     </source>
     EOF
   

   除了建立新檔案，您也可以將設定資訊新增至現有設定檔。

3. 重新啟動代理程式，以套用設定變更：

   sudo service google-fluentd restart
   

4. 在記錄檔中產生記錄檔的記錄：

   echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
   

5. 查看 Logs Explorer，檢視所擷取的記錄項目：

   {
     insertId:  "1m9mtk4g3mwilhp"
     jsonPayload: {
     code:  "structured-log-code"
     message:  "This is a log from the log file at test-structured-log.log"
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/structured-log"
     receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T01:53:39.071920609Z"
   }
   

   在記錄檔探索工具中，依資源類型和 structured-log 的 logName 篩選。

關於針對常用第三方應用程式，自訂記錄檔輸入格式的其他選項，請參閱常用記錄檔格式及使用方式一文。

透過 in_forward 外掛程式串流結構化 (JSON) 記錄

此外，您也可以透過 fluentd in_forward 外掛程式傳送記錄。fluentd-cat 是內建工具，可輕鬆將記錄傳送至 in_forward 外掛程式。fluentd說明文件內有這項工具的更多詳細資訊。

如要透過 fluentd in_forward 外掛程式傳送記錄檔，請參閱以下操作說明：

1. 在安裝記錄代理程式的 VM 上執行下列指令：

   echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
   

2. 查看 Logs Explorer，檢視所擷取的記錄項目：

   {
     insertId:  "1kvvmhsg1ib4689"
     jsonPayload: {
     code:  "send-log-via-fluent-cat"
     message:  "This is a log from in_forward plugin."
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
     receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T02:11:22.717692494Z"
   }
   

串流來自應用程式程式碼的結構化 (JSON) 記錄檔

您可以啟用多種語言的連接器，傳送來自應用程式程式碼的結構化記錄檔；詳情請參閱 fluentd 說明文件。這些連接器是以 in_forward 外掛程式為基礎建構。

設定記錄項目標籤

下列設定選項可在擷取記錄檔到 Cloud Logging 時，覆寫 LogEntry 標籤和 MonitoredResource 標籤。所有記錄項目都會與受控資源相關聯。如需更多資訊，請查看 Cloud Logging 受控資源類型清單。

記錄代理程式輸出外掛程式支援三種 LogEntry 標籤的設定方式：

• 動態方式，使用不同的標籤取代結構化項目中的特定標籤。詳情請參閱本頁的「在結構化記錄項目中設定標籤」一節。
• 靜態方式，只要某個值出現，即加上標籤。詳情請參閱本頁的「靜態設定標籤」一節。

在結構化記錄項目中設定標籤

假設您編寫了如下的結構化記錄項目酬載：

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

並且假設您想要將酬載欄位 env 轉換為中繼資料標籤 environment。如要這麼做，請將下列內容新增到主設定檔 (Linux 上的 /etc/google-fluentd/google-fluentd.conf 或 Windows 上的 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf) 中的輸出外掛程式設定中：

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

此處的 label_map 設定會以 environment 取代酬載中的 env 標籤，因此產生的記錄項目會有標籤 environment，其值為 production。

靜態設定標籤

如果您在酬載中沒有這項資訊，只想新增名為 environment 的靜態中繼資料標籤，請將下列內容新增到主設定檔 (Linux 上的 /etc/google-fluentd/google-fluentd.conf 或 Windows 上的 C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf) 中的輸出外掛程式設定中：

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

在此情況下，無論記錄項目是否已有標籤，系統都會使用 labels 設定，將含有指定常值的標籤附加到該項目，而非使用對應來取代標籤。即便要傳送的是未結構化的記錄檔，也可以使用此方式。

如要進一步瞭解如何設定 labels、label_map 和其他 Logging 代理程式設定，請參閱本頁的「設定記錄項目標籤」一節。

編輯記錄

Fluentd 提供內建篩選器外掛程式，可用來修改記錄項目。

最常用的篩選器外掛程式為 filter_record_transformer，可用來：

• 新增欄位到記錄項目
• 更新記錄項目的欄位
• 刪除記錄項目的欄位

有些輸出外掛程式也可編輯記錄項目。fluent-plugin-record-reformer 輸出外掛程式提供的功能與 filter_record_transformer 篩選器外掛程式類似，但可用來編輯記錄檔標記。這個外掛程式可能需要使用較多資源，每次更新記錄檔標記時，就會產生具有新標記的新記錄項目。請注意，設定中的 tag 欄位為必填欄位；我們也建議您修改這個欄位，避免進入死循環。

fluent-plugin-detect-exceptions 輸出外掛程式可掃描多行例外狀況堆疊追蹤的非結構化 (文字) 或 JSON 格式記錄檔的記錄串流。若有連續的記錄項目組成例外狀況堆疊追蹤，這些記錄項目便會以單ㄧ組合記錄訊息的形式轉送，否則就會按原樣轉送記錄項目。

進階 (非預設) 設定定義

如果您想自訂 Logging 代理程式的設定 (除了預設設定)，請繼續閱讀本頁。

緩衝相關設定選項

您可以使用下列設定選項調整記錄代理程式內部的緩衝機制。

專案與監控資源相關的設定選項

您可以使用下列設定選項，手動指定 MonitoredResource 物件中的專案和特定欄位。這些值會由記錄代理程式自動收集，因此不建議您手動指定這些值。

其他輸出外掛程式設定選項

¹在 App EngineVM 彈性環境與 Google Kubernetes Engine 執行的 VM 執行個體中，此功能預設為啟用。

套用自訂代理程式設定

您可以自訂 Logging 代理程式，新增自己的 fluentd 設定檔：

如要進一步瞭解 fluentd 設定檔，請參閱 fluentd 設定檔語法說明文件。