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

設定 Logging 代理程式

自訂 Cloud Logging 代理程式設定後，您就能將虛擬機器 (VM) 執行個體上檔案和第三方應用程式的其他記錄串流至 Logging。Logging 代理程式包含收集常見系統和應用程式記錄檔的預設設定，因此只有在您要自訂記錄檔收集作業，或檢查代理程式如何處理記錄檔記錄時，才需要修改設定。

預設設定

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

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

Logging 代理程式的運作方式。

Logging 代理程式會使用 fluentd 輸入外掛程式，從外部來源 (例如磁碟上的檔案) 擷取及提取事件記錄，或剖析傳入的記錄。輸入外掛程式會與代理程式綁定，或可做為 Ruby gem 獨立安裝；請查看綁定外掛程式清單。

代理程式會使用 fluentd 的內建 in_tail 外掛程式，讀取儲存在 VM 執行個體記錄檔中的記錄檔記錄。每筆記錄都會轉換為 Cloud Logging 的記錄項目結構。每筆記錄的內容大多記錄在記錄項目的「酬載」中，但記錄項目也包含「時間戳記」和「嚴重性」等標準元素。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

如果您執行的是 1.5 版之前的 Logging 代理程式，位置如下： C:\GoogleStackdriverLoggingAgent\fluent.conf

Syslog 設定

設定檔位置：/etc/google-fluentd/config.d/syslog.conf
說明：此檔案內的設定會將 syslog 設為記錄檔輸入來源。
查看設定存放區。

設定名稱	類型	預設	說明
`format`	字串	`/^(?<message>(?<time>[^ ]\s[^ ]* [^ ]) .)$/`	syslog 的格式。
`path`	字串	`/var/log/syslog`	syslog 檔案的路徑。
`pos_file`	字串	`/var/lib/google-fluentd/pos/syslog.pos`	這個記錄輸入項的位置檔案路徑。`fluentd` 會將上次讀取的位置記錄到這個檔案。詳閱 `fluentd` 說明文件。
`read_from_head`	bool	`true`	是否要從檔案開頭 (而非底部) 開始讀取記錄。詳閱 `fluentd` 說明文件。
`tag`	字串	`syslog`	此次記錄檔輸入的記錄檔標記。

`in_forward` 輸入外掛程式設定

設定檔位置：/etc/google-fluentd/config.d/forward.conf
說明：這個檔案包含 in_forward fluentd 輸入外掛程式的設定。in_forward 輸入外掛程式可讓您使用 TCP 通訊端傳入記錄。
請參閱這個外掛程式和設定存放區的詳細 fluentd 說明文件。

設定名稱	類型	預設	說明
`port`	int	`24224`	要監控的連接埠。
`bind`	字串	`127.0.0.1`	要監控的綁定位址。預設情況下，僅接受來自 localhost 的連線。如要開放存取權，請將這項設定變更為 `0.0.0.0`。

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

設定檔位置： /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
說明：這個目錄包含設定檔，可將第三方應用程式的記錄檔指定為記錄輸入。除了 syslog.conf 和 forward.conf 之外，每個檔案都代表一個應用程式 (例如 apache.conf 代表 Apache 應用程式)。
查看設定存放區。

設定名稱	類型	預設	說明
`format`¹	字串	視應用程式而定	記錄檔格式，詳閱 `fluentd` 說明文件。
`path`	字串	視應用程式而定	記錄檔的路徑。您可以指定多個路徑，並以「,」分隔。您可以使用 `*` 萬用字元和 strftime 格式，動態新增或移除監控的檔案。詳閱 `fluentd` 說明文件。
`pos_file`	字串	視應用程式而定	這個記錄輸入項的位置檔案路徑。`fluentd` 會將上次讀取的位置記錄到這個檔案。詳閱 `fluentd` 說明文件。
`read_from_head`	bool	`true`	是否要從檔案開頭 (而非底部) 開始讀取記錄。詳閱 `fluentd` 說明文件。
`tag`	字串	應用程式名稱，各不相同。	此次記錄檔輸入的記錄檔標記。

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

Google Cloud `fluentd` 輸出外掛程式設定

設定檔位置：
- Linux：/etc/google-fluentd/google-fluentd.conf
- Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  如果您執行的是 1.5 版之前的 Logging 代理程式，位置如下： C:\GoogleStackdriverLoggingAgent\fluent.conf
說明：這個檔案包含設定選項，可控管Google Cloud fluentd 輸出外掛程式的行為。
前往設定存放區。

設定名稱	類型	預設	說明
`buffer_chunk_limit`	字串	`512KB`	記錄檔記錄傳入時，如果無法快速寫入下游元件，就會推送至區塊佇列。此設定用以限制各區塊的大小。根據預設，區塊限制會設為保守值，以免超過 Logging API 中每個寫入要求建議的區塊大小 (5 MB)。API 要求中的記錄項目可能比原始記錄大 5 到 8 倍，並附加所有額外的中繼資料。如果符合下列任一條件，緩衝區區塊就會清除： 1. 達到`flush_interval`。 2. 緩衝區空間達到 `buffer_chunk_limit`。
`flush_interval`	字串	`5s`	記錄檔記錄傳入時，如果無法快速寫入下游元件，就會推送至區塊佇列。這項設定會決定緩衝區塊清除前的時間長度。如果符合下列任一條件，緩衝區區塊就會清除： 1. 達到`flush_interval`。 2. 緩衝區空間達到 `buffer_chunk_limit`。
`disable_retry_limit`	bool	`false`	強制限制無法清除緩衝區塊時的重試次數上限。請參閱 `retry_limit`、`retry_wait` 和 `max_retry_wait`，查看詳細規格。
`retry_limit`	整數	`3`	緩衝區區塊無法清除時，`fluentd` 預設會稍後重試。在捨棄某個有問題的緩衝區塊前，此設定會定出需執行的重試次數。
`retry_wait`	整數	`10s`	緩衝區區塊無法清除時，`fluentd` 預設會稍後重試。此設定會設下第一次重試前的等待間隔秒數。每次重試時，等待間隔會加倍 (20 秒、40 秒…)，直到達到 `retry_limit` 或 `max_retry_wait` 為止。
`max_retry_wait`	整數	`300`	緩衝區區塊無法清除時，`fluentd` 預設會稍後重試。每次重試時，等待間隔會加倍 (20 秒、40 秒等)。這項設定會以秒為單位，設定等待間隔上限。如果等待間隔達到此限制，就會停止加倍時間。
`num_threads`	int	`8`	輸出外掛程式同時可處理的記錄檔清理次數。
`use_grpc`	bool	`true`	是否要使用 gRPC (而非 REST/JSON) 與 Logging API 通訊。啟用 gRPC 後，CPU 使用率通常會降低。
`grpc_compression_algorithm`	列舉	`none`	如果使用 gRPC，請設定要使用的壓縮結構定義。可以是 `none` 或 `gzip`。
`partial_success`	bool	`true`	是否支援部分成功的記錄擷取。如果設為 `true`，系統會捨棄整組記錄中的無效記錄項目，並將有效記錄項目成功擷取至 Logging API。如果設為 `false`，則只要完整組合中含有任何無效的記錄項目，就會遭到捨棄。
`enable_monitoring`	bool	`true`	設為 `true` 時，Logging 代理程式會匯出內部遙測資料。詳情請參閱「輸出外掛程式遙測」。
`monitoring_type`	字串	`opencensus`	監控類型。支援的選項為 `opencensus` 和 `prometheus`。詳情請參閱「輸出外掛程式遙測」。
`autoformat_stackdriver_trace`	bool	`true`	如果設為 `true`，且結構化酬載欄位 `logging.googleapis.com/trace` 的值符合 ResourceTrace `traceId` 格式，系統就會重新設定追蹤記錄格式。如要進一步瞭解自動格式設定，請參閱本頁的「結構化酬載中的特殊欄位」。

監控功能設定

本節說明 Cloud Monitoring 設定。

輸出外掛程式遙測

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 代理程式，才能將這些指標寫入 Monitoring API。

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

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

agent.googleapis.com/agent/uptime (含有 version 標籤)：Logging 代理程式的運作時間。
agent.googleapis.com/agent/log_entry_count，標籤為 response_code：Logging 代理程式寫入的記錄項目數量。
agent.googleapis.com/agent/log_entry_retry_count，標籤為 response_code：Logging 代理程式寫入的記錄項目數量。
agent.googleapis.com/agent/request_count，標籤為 response_code：Logging 代理程式的 API 要求數量。

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

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

uptime 搭配 version 標籤：Logging 代理程式的運作時間。
stackdriver_successful_requests_count 搭配 grpc 和 code 標籤：Logging API 的成功要求數量。
含有 grpc 和 code 標籤的 stackdriver_failed_requests_count：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 外掛程式的指標。詳情請參閱「透過 Prometheus 監控」。
前往設定存放區。

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

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

處理酬載

在 Logging 代理程式的預設設定下，大多數支援的記錄都來自記錄檔，並以非結構化 (文字) 酬載的形式擷取至記錄項目。

唯一的例外狀況是 in_forward 輸入外掛程式 (預設也會啟用)，只接受結構化記錄，並將其擷取為記錄項目中的結構化 (JSON) 酬載。詳情請參閱本頁的「使用 in_forward 外掛程式串流結構化 (JSON) 記錄」一節。

如果記錄行是序列化的 JSON 物件，且已啟用 detect_json 選項，輸出外掛程式會將記錄項目轉換為結構化 (JSON) 酬載。在 App Engine 彈性環境中執行的 VM 執行個體預設會啟用這個選項。在 App Engine 標準環境中執行的 VM 執行個體，預設不會啟用這個選項。啟用 detect_json 選項後，剖析的任何 JSON 一律會擷取為 jsonPayload。

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

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

結構化酬載中的特殊欄位

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

JSON 記錄欄位	`LogEntry` 欄位	Cloud Logging 代理程式函式	範例值
`severity`	`severity`	Logging 代理程式會嘗試比對各種常見的嚴重性字串，包括 Logging API 辨識的 LogSeverity 字串清單。	`"severity":"ERROR"`
`message`	`textPayload` (或 `jsonPayload` 的一部分)	Logs Explorer 中記錄項目行顯示的訊息。	`"message":"There was an error in the application."` 注意：如果 Logging 代理程式移動其他特殊用途欄位後，是唯一留下的欄位，且 `detect_json` 未啟用，則 `message` 會儲存為 `textPayload`；否則 `message` 會保留在 `jsonPayload` 中。`detect_json` 不適用於 Google Kubernetes Engine 等代管記錄環境。如果記錄項目包含例外狀況堆疊追蹤，則應在這個 `message` JSON 記錄欄位中設定例外狀況堆疊追蹤，以便剖析例外狀況堆疊追蹤並儲存至 Error Reporting。
`log` (僅限舊版 Google Kubernetes Engine)	`textPayload`	僅適用於舊版 Google Kubernetes Engine：如果移動特殊用途欄位後，只剩下 `log` 欄位，該欄位會儲存為 `textPayload`。
`httpRequest`	`httpRequest`	`LogEntry` `HttpRequest` 欄位格式的結構化記錄。	`"httpRequest":{"requestMethod":"GET"}`
時間相關欄位	`timestamp`	詳情請參閱「時間相關欄位」。	`"time":"2025-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	詳情請參閱「`LogEntry`」頁面的「`insertId`」一節。	`"logging.googleapis.com/insertId":"42"`
`logging.googleapis.com/labels`	`labels`	這個欄位的值必須是結構化記錄。詳情請參閱「`LogEntry`」頁面上的 `labels`。	`"logging.googleapis.com/labels":` `{"user_label_1":"value_1","user_label_2":"value_2"}`
`logging.googleapis.com/operation`	`operation`	Logs Explorer 也會使用這個欄位的值，將相關記錄項目分組。詳情請參閱「`LogEntry`」頁面的「`operation`」一節。	`"logging.googleapis.com/operation":` `{"id":"get_data","producer":"github.com/MyProject/MyApplication",` `"first":"true"}`
`logging.googleapis.com/sourceLocation`	`sourceLocation`	與記錄項目相關聯的原始碼位置資訊 (如有)。詳情請參閱「`LogEntry`」頁面的「`LogEntrySourceLocation`」一節。	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	記錄項目相關聯追蹤記錄中的 Span ID。詳情請參閱「`LogEntry`」頁面的「`spanId`」一節。	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	與記錄項目相關聯的追蹤記錄資源名稱 (如有)。詳情請參閱「`LogEntry`」頁面的「`trace`」一節。	`"logging.googleapis.com/trace":"[TRACE_ID]"` `"logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]"` 注意：如果不是寫入 `stdout` 或 `stderr`，請將這個欄位格式設為 `[TRACE_ID]`，或使用舊版格式 `projects/[PROJECT_ID]/traces/[TRACE_ID]`。這兩種格式都能讓 Logs Explorer 和 Trace Explorer 建立記錄和追蹤記錄資料的關聯。如果 `autoformat_stackdriver_trace` 為 true，且 `[V]` 符合 ResourceTrace 物件中 `traceId` 欄位的格式，則 LogEntry `trace` 欄位的值為 `projects/[PROJECT_ID]/traces/[V]`。
`logging.googleapis.com/trace_sampled`	`traceSampled`	這個欄位的值必須是 `true` 或 `false`。詳情請參閱「`LogEntry`」頁面的「`traceSampled`」一節。	`"logging.googleapis.com/trace_sampled": false`

時間相關欄位

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

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

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

搜尋 timestamp 欄位，該欄位是包含 seconds 和 nanos 欄位的 JSON 物件，分別代表從世界標準時間紀元起算的帶正負號秒數，以及非負數的小數秒數：
```
jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```

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

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

如果上述搜尋失敗，請搜尋 time 欄位，該欄位是 RFC 3339 格式的字串：
```
jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}
```

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

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

自訂代理程式設定

除了 Logging 代理程式預設串流的預設記錄清單之外，您也可以自訂 Logging 代理程式，將其他記錄傳送至 Logging，或新增輸入設定來調整代理程式設定。

這些區段中的設定定義僅適用於 fluent-plugin-google-cloud 輸出外掛程式，並指定記錄檔如何轉換及擷取至 Cloud Logging。

主設定檔位置：
- Linux：/etc/google-fluentd/google-fluentd.conf
- Windows：C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  如果您執行的是 1.5 版之前的 Logging 代理程式，位置如下： C:\GoogleStackdriverLoggingAgent\fluent.conf
說明：這個檔案包含設定選項，可控管 fluent-plugin-google-cloud 輸出外掛程式的行為。
查看設定存放區。

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

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

使用記錄檔串流非結構化 (文字) 記錄

在 Linux 命令提示字元中建立記錄檔：
```
touch /tmp/test-unstructured-log.log
```

在額外設定目錄 /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 the position in the log
    # file that has already been processed. 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

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

重新啟動代理程式，以套用設定變更：
```
sudo service google-fluentd restart
```

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

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

查看 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}

如要設定 Logging 代理程式擷取 JSON 格式的內容，請按照下列步驟操作：

在 Linux 命令提示字元中建立記錄檔：
```
touch /tmp/test-structured-log.log
```

在額外設定目錄 /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 the position in the log
    # file that has already been processed. 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

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

重新啟動代理程式，以套用設定變更：
```
sudo service google-fluentd restart
```

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

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

查看 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"
}

在 Logs Explorer 中，依資源類型和 structured-log 的 logName 篩選。

如需其他選項，瞭解如何自訂常見第三方應用程式的記錄輸入格式，請參閱「常見記錄格式和剖析方式」。

使用 `in_forward` 外掛程式串流結構化 (JSON) 記錄

此外，您也可以使用 fluentd in_forward 外掛程式傳送記錄。fluentd-cat 是內建工具，可協助將記錄傳送至 in_forward 外掛程式。如要進一步瞭解這項工具，請參閱 fluentd 說明文件。

如要使用 fluentd in_forward 外掛程式傳送記錄，請參閱下列操作說明：

在已安裝 Logging 代理程式的 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

查看 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 受監控資源類型清單。

設定名稱	類型	預設	說明
`label_map`	hash	nil	`label_map` (指定為 JSON 物件) 是 `fluentd` 欄位名稱的未排序組合，其值會以標籤形式傳送，而非結構化酬載的一部分。對應表中的每個項目都是 {`field_name`: `label_name`} 配對。遇到 `field_name` (由輸入外掛程式剖析) 時，系統會將含有對應 `label_name` 的標籤新增至記錄項目。欄位中的值會做為該標籤的值。對應關係可讓您更靈活地指定標籤名稱，包括使用不符合 `fluentd` 欄位名稱規定的字元。如需範例，請參閱「在結構化記錄項目中設定標籤」。
`labels`	hash	nil	`labels` (指定為 JSON 物件) 是設定時提供的一組自訂標籤。您可以將額外的環境資訊插入每則訊息，或自訂系統自動偵測到的標籤。對應表中的每個項目都是 {`label_name`: `label_value`} 配對。

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 設定會將酬載中的 env 標籤替換為 environment，因此產生的記錄項目會包含標籤 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 代理程式的設定，而非使用預設設定，請繼續閱讀本頁面。

緩衝相關設定選項

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

設定名稱	類型	預設	說明
`buffer_type`	字串	`buf_memory`	如果記錄無法快速寫入 Logging API，就會推送至緩衝區。緩衝區可以位於記憶體或檔案中。建議值：`buf_file`。預設的 `buf_memory` 速度很快，但不會保留。記錄檔可能遺失。如果 `buffer_type` 為 `buf_file`，則必須一併指定 `buffer_path`。
`buffer_path`	字串	使用者指定	緩衝區塊儲存的路徑。如果 `buffer_type` 為 `buf_file`，則必須提供這項參數。此設定不得重複，以免形成競爭狀況。
`buffer_queue_limit`	int	`64`	指定區塊佇列的長度限制。緩衝區佇列達到這項限制時，緩衝區行為會由 `buffer_queue_full_action` 控制。根據預設，系統會擲回例外狀況。這個選項與 `buffer_chunk_limit` 搭配使用，可決定 `fluentd` 用於緩衝處理的最大磁碟空間。
`buffer_queue_full_action`	字串	`exception`	在緩衝佇列已滿時，控制緩衝行為。可能的值： 1. `exception`：佇列已滿時擲回 `BufferQueueLimitError`。`BufferQueueLimitError` 的處理方式取決於輸入外掛程式。舉例來說，`in_tail` 輸入外掛程式會停止讀取新行，而 `in_forward` 輸入外掛程式則會傳回錯誤。 2. `block`：這個模式會停止輸入外掛程式執行緒，直到緩衝區已滿的情況解決為止。這項動作適合批次處理等用途。`fluentd` 不建議使用封鎖動作來避免 `BufferQueueLimitError`。如果經常達到 `BufferQueueLimitError`，表示目的地容量不足以處理流量。 3. `drop_oldest_chunk`：這個模式會捨棄最舊的區塊。

專案和受監控資源相關設定選項

您可以透過下列設定選項，手動指定專案和 MonitoredResource 物件中的特定欄位。Logging 代理程式會自動收集這些值，不建議您手動指定。

設定名稱	類型	預設	說明
`project_id`	字串	nil	如果指定，這會覆寫 `project_id`，識別 Logging 代理程式執行的基礎 Google Cloud 或 AWS 專案。
`zone`	字串	nil	若指定，此設定會覆寫該區域。
`vm_id`	字串	nil	如果指定，則會覆寫 VM ID。
`vm_name`	字串	nil	若指定，此設定會覆寫 VM 名稱。

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

設定名稱	類型	預設	說明
`detect_json`¹	bool	`false`	是否嘗試偵測記錄檔記錄是否為含有需要剖析的 JSON 內容的文字記錄項目。如果這個選項為 `true`，且系統偵測到非結構化 (文字) 記錄項目為 JSON 格式，就會剖析該項目，並以結構化 (JSON) 酬載的形式傳送。
`coerce_to_utf8`	bool	`true`	是否允許在使用者記錄檔中使用非 UTF-8 字元。如果設為 `true`，任何非 UTF-8 字元都會替換為 `non_utf8_replacement_string` 指定的字串。如果設為 `false`，任何非 UTF-8 字元都會導致外掛程式發生錯誤。
`require_valid_tags`	bool	`false`	是否拒絕含有無效標記的記錄項目。如果這個選項設為 `false`，系統會將所有非字串標記轉換為字串，並清除所有非 UTF-8 或其他無效字元，讓標記生效。
`non_utf8_replacement_string`	字串	`""` (空字串) 或 `" "`(空格)	如果 `coerce_to_utf8` 設為 `true`，任何非 UTF-8 字元都會替換為這裡指定的字串。

¹在 App Engine 彈性環境中執行的 VM 執行個體，預設會啟用這項功能。

套用自訂代理程式設定

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

Linux 執行個體

將您的設定檔複製至以下目錄：
```
/etc/google-fluentd/config.d/
```
Logging 代理程式安裝指令碼會使用預設的 catch-all 設定檔填入這個目錄。詳情請參閱「取得 Logging 代理程式原始碼」。
選用。執行下列指令，驗證設定變更：
```
sudo service google-fluentd configtest
```
執行下列指令，重新啟動代理程式：
```
sudo service google-fluentd force-reload
```

Windows 執行個體

將設定檔複製到代理程式安裝目錄的 config.d 子目錄。如果接受的是預設安裝目錄，該目錄為：
```
C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
```
在指令列殼層中執行下列指令，重新啟動代理程式：
```
net stop StackdriverLogging
net start StackdriverLogging
```

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

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

預設設定

預設設定定義

根設定檔位置

Syslog 設定

in_forward 輸入外掛程式設定

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

Google Cloud fluentd 輸出外掛程式設定

監控功能設定

輸出外掛程式遙測

prometheus 和 prometheus_monitor 外掛程式設定

處理酬載

結構化酬載中的特殊欄位

時間相關欄位

自訂代理程式設定

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

使用記錄檔串流非結構化 (文字) 記錄

使用記錄檔串流結構化 (JSON) 記錄

使用 in_forward 外掛程式串流結構化 (JSON) 記錄

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

設定記錄項目標籤

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

靜態設定標籤

編輯記錄

進階 (非預設) 設定定義

緩衝相關設定選項

專案和受監控資源相關設定選項

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

套用自訂代理程式設定

Linux 執行個體

Windows 執行個體

設定 Logging 代理程式

`in_forward` 輸入外掛程式設定

Google Cloud `fluentd` 輸出外掛程式設定

使用 `in_forward` 外掛程式串流結構化 (JSON) 記錄