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

設定 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 設為記錄檔輸入來源。
查看設定存放區。

設定名稱	類型	預設	說明
`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
  
  如果您執行的 Logging 代理程式是 v1-5 之前的版本，位置為：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`	enum	`none`	如果使用 gRPC，則會設定要使用的壓縮配置。可以是 `none` 或 `gzip`。
`partial_success`	bool	`true`	是否支援部分成功的記錄擷取。如果為 `true`，系統會捨棄完整集合中的無效記錄項目，並將有效記錄項目成功擷取至 Logging API。如果是 `false`，則如果完整集合包含任何無效的記錄項目，就會捨棄該集合。
`enable_monitoring`	bool	`true`	設為 `true` 時，記錄代理程式會匯出內部遙測資料。詳情請參閱「輸出外掛程式追蹤資料」。
`monitoring_type`	字串	`opencensus`	監控類型。支援的選項為 `opencensus` 和 `prometheus`。詳情請參閱「輸出外掛程式遙測資料」。
`autoformat_stackdriver_trace`	bool	`true`	設為 `true` 時，如果結構化酬載欄位 `logging.googleapis.com/trace` 的值與 ResourceTrace `traceId` 格式相符，系統會重新設定追蹤記錄的格式。如要進一步瞭解自動格式設定，請參閱本頁的「結構化酬載中的特殊欄位」。

監控功能設定

輸出外掛程式遙測

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 欄位。

JSON 記錄欄位	`LogEntry` 欄位	Cloud Logging 代理函式	範例值
`severity`	`severity`	記錄代理程式會嘗試比對各種常見的嚴重性字串，包括 Logging API 所辨識的 LogSeverity 字串清單。	`"severity":"ERROR"`
`message`	`textPayload` (或 `jsonPayload` 的一部分)	Logs Explorer 記錄項目列中顯示的訊息。	`"message":"There was an error in the application."` 注意：如果 `message` 是記錄代理程式移動其他特殊用途欄位後剩下的唯一欄位，且 `detect_json` 未啟用，則會儲存為 `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":"2020-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`	記錄項目相關聯追蹤記錄中的時距 ID。詳情請參閱 `LogEntry` 頁面中的 `spanId`。	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	記錄檔項目相關聯追蹤記錄的資源名稱 (如果有的話)。詳情請參閱 `LogEntry` 頁面中的 `trace`。	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` 注意：如果未寫入 `stdout` 或 `stderr`，則此欄位的值應以 `projects/[PROJECT-ID]/traces/[TRACE-ID]` 格式設定，以便 Logs Explorer 和 Trace Viewer 將記錄項目分組，並與追蹤記錄一併顯示。如果 `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"
}

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

搜尋 timestamp 欄位，這是 JSON 物件，其中包含 seconds 和 nanos 欄位，分別代表從世界標準時間紀元後帶正負號的秒數，以及非負數小數秒數：
```
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
}
```

找到時間相關資訊後，記錄代理程式會使用該資訊設定 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。

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

透過 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 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

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

重新啟動代理程式，以套用設定變更：
```
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}

如要設定記錄代理程式以擷取 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 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

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

重新啟動代理程式，以套用設定變更：
```
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"
}

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

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

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

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

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

在安裝記錄代理程式的 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`} 組合。

記錄代理程式輸出外掛程式支援三種 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 代理程式的設定 (除了預設設定)，請繼續閱讀本頁。

緩衝相關設定選項

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

設定名稱	類型	預設	說明
`buffer_type`	字串	`buf_memory`	無法快速寫入 Logging API 的記錄會推送至緩衝區。緩衝區可位於記憶體或實際檔案中。建議值：`buf_file`。預設的 `buf_memory` 雖然速度快，但不會持續存在。有遺失記錄的風險。如果 `buffer_type` 為 `buf_file`，則也必須指定 `buffer_path`。
`buffer_path`	字串	使用者指定	緩衝區塊儲存的路徑。如果 `buffer_type` 為 `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 物件中的專案和特定欄位。這些值會由記錄代理程式自動收集，因此不建議您手動指定這些值。

設定名稱	類型	預設	說明
`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 EngineVM 彈性環境與 Google Kubernetes Engine 執行的 VM 執行個體中，此功能預設為啟用。

套用自訂代理程式設定

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

Linux 執行個體

將您的設定檔複製至以下目錄：
```
/etc/google-fluentd/config.d/
```
記錄代理程式安裝指令碼會以預設的全部接收設定檔填入此目錄。如需更多資訊，請參閱取得記錄代理程式原始碼一文。
(非必要) 執行下列指令，驗證設定變更：
```
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) 記錄