Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設定 Logging 代理程式

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

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

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

預設設定

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

在預設設定中，Logging 代理程式會將預設記錄清單中包含的記錄串流至 Cloud 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

如果您執行的 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`	列舉	`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 端點 (預設為 localhost:24231/metrics；如要瞭解如何自訂，請參閱 prometheus 和 prometheus_monitor 外掛程式設定) 以 Prometheus 格式公開指標。在 Compute Engine VM 上，如要將這些指標寫入 Monitoring API，也必須安裝並執行 Monitoring 代理程式。

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

在 opencensus 模式下，Monitoring 代理程式和 Logging 代理程式都會將下列指標寫入 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 label: Logging 代理程式寫入的記錄項目數量。
agent.googleapis.com/agent/request_count，並加上 response_code 標籤： Logging 代理程式發出的 API 要求數量。

如要進一步瞭解這些指標，請參閱「服務專員指標」頁面。

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

uptime 具有 version 標籤： Logging 代理程式的正常運作時間。
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 標籤： Logging API 拒絕的記錄項目數量。grpccode
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>

處理酬載

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

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

當記錄檔記錄為序列化 JSON 物件，且 detect_json 選項為啟用，輸出外掛程式會將記錄檔項目轉換為結構化的 (JSON) 酬載。在 App Engine 彈性環境和 Google Kubernetes 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 API 可辨識的 LogSeverity 字串清單。	`"severity":"ERROR"`
`message`	`textPayload` (或部分 `jsonPayload`)	Logs Explorer 中記錄項目行顯示的訊息。	`"message":"There was an error in the application."` 注意：如果記錄代理程式移動其他特殊用途欄位後，只剩下 `message`，且未啟用和 `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":"2020-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	詳情請參閱`insertIdLogEntry`頁面。	`"logging.googleapis.com/insertId":"42"`
`logging.googleapis.com/labels`	`labels`	這個欄位的值必須是結構化記錄。詳情請參閱`labels` `LogEntry` 頁面。	`"logging.googleapis.com/labels":` `{"user_label_1":"value_1","user_label_2":"value_2"}`
`logging.googleapis.com/operation`	`operation`	Logs Explorer 也會使用這個欄位的值，將相關記錄項目分組。詳情請參閱`operationLogEntry`頁面。	`"logging.googleapis.com/operation":` `{"id":"get_data","producer":"github.com/MyProject/MyApplication",` `"first":"true"}`
`logging.googleapis.com/sourceLocation`	`sourceLocation`	與記錄項目相關聯的原始碼位置資訊 (如有)。詳情請參閱`LogEntrySourceLocationLogEntry`頁面。	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	記錄項目相關聯追蹤記錄中的時距 ID。詳情請參閱`spanIdLogEntry`頁面。	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	記錄項目相關聯追蹤記錄的資源名稱 (如有)。詳情請參閱`traceLogEntry`頁面。	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` 注意：如果不是寫入 `stdout` 或 `stderr`，這個欄位的值應格式化為 `projects/[PROJECT-ID]/traces/[TRACE-ID]`，這樣記錄探索器和追蹤檢視器就能使用這個值，將記錄項目分組，並與追蹤記錄一併顯示。如果 `autoformat_stackdriver_trace` 為 true 且 `[V]` 符合 ResourceTrace `traceId` 的格式，則 LogEntry `trace` 欄位的值為 `projects/[PROJECT-ID]/traces/[V]`。
`logging.googleapis.com/trace_sampled`	`traceSampled`	這個欄位的值必須是 `true` 或 `false`。詳情請參閱`traceSampledLogEntry`頁面。	`"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
  
  如果您執行的 Logging 代理程式是 v1-5 之前的版本，位置為： 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 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

查看記錄探索工具，檢視所擷取的記錄項目：

{
  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 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

查看記錄探索工具，檢視所擷取的記錄項目：

{
  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 外掛程式傳送記錄檔，請參閱以下操作說明：

安裝記錄代理程式後，在 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

查看記錄探索工具，檢視所擷取的記錄項目：

{
  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 代理程式的設定 (超出預設設定)，請繼續閱讀本頁內容。

緩衝相關設定選項

您可以透過下列設定選項，調整 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 物件中的特定欄位。這些值是由 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 EngineVM 彈性環境與 Google Kubernetes Engine 執行的 VM 執行個體中，此功能預設為啟用。

套用自訂代理程式設定

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

Linux 執行個體

將您的設定檔複製至以下目錄：
```
/etc/google-fluentd/config.d/
```
記錄代理程式安裝指令碼會在這個目錄中填入預設的全面擷取設定檔。詳情請參閱「取得 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) 記錄檔