上游 Fluentd 的設定相容性

從 Logging 代理程式遷移至上游 Fluentd 時，您可能會遇到設定不相容的問題，需要採取因應措施，避免啟動錯誤。本文說明如何解決設定不相容的問題。

舊版 Logging 代理程式與上游 Fluentd 之間的語法變更

舊版 Logging 代理程式採用 Fluentd v0.12 語法，但上游 Fluentd 採用 v1 標準。這項轉換作業會淘汰各種參數，並導入新的巢狀指令來處理核心功能，取代先前使用的扁平式設定結構。

為避免啟動失敗並確保系統正確處理記錄，請務必移除或替換已淘汰的參數。以下各節說明如何更新已淘汰的參數。

輸出外掛程式設定

下表列出輸出外掛程式設定中必須更新的參數，以免發生錯誤：

舊版 Logging 代理程式語法 上游 Fluentd 語法 附註
不適用 <buffer> Fluentd 輸出外掛程式支援 <match> 區段下的 <buffer> 區段，可設定事件緩衝。詳情請參閱 Fluentd 說明文件的「Config: Buffer Section」。
buffer_type @type
buffer_path path
buffer_chunk_limit chunk_limit_size
disable_retry_limit retry_forever
retry_limit retry_max_times
max_retry_wait retry_max_interval
num_threads flush_thread_count
partial_success 不適用 移除這項參數。上游 Fluentd 預設會永久啟用部分成功，只會捨棄無效的行。

以下是舊版 Logging 代理程式中 google-cloud 輸出外掛程式設定的範例：

<match **>
  @type google_cloud
  buffer_type file
  buffer_path /var/log/google-fluentd/buffers
  buffer_chunk_limit 512KB
  flush_interval 5s
  disable_retry_limit false
  retry_limit 3
  retry_wait 10
  max_retry_wait 300
  num_threads 8
</match>

更新後，設定如下所示：

<match **>
  @type google_cloud
  <buffer>
    @type file
    path /var/log/google-fluentd/buffers
    chunk_limit 512KB
    flush_interval 5s
    retry_forever false
    retry_max_times 3
    retry_wait 10
    retry_max_interval 300
    flush_thread_count 8
  </buffer>
</match>

輸入外掛程式設定

下表列出輸入外掛程式設定中必須更新的參數，以免發生錯誤：

舊版 Logging 代理程式語法 上游 Fluentd 語法 附註
format <parse> 詳情請參閱 Fluentd 說明文件的「Config: Parse Section」。
protocol_type <transport> 指出 syslog 傳輸的通訊協定，可以是 udp、tcp, 或 tls。
auto_typecast 在 json 解析外掛程式中使用時，請移除這個參數。

以下是舊版 Logging 代理程式的輸入外掛程式設定範例：

<source>
    @type tail
    path /var/log/my-app.log
    format json
</source>

更新後，設定如下所示：

<source>
    @type tail
    path /var/log/my-app.log
    <parse>
      @type json
    </parse>
</source>

Ruby Time 物件序列化

上游 Fluentd 需要明確轉換在 <record> 篩選器內使用的原始 Ruby Time 物件，例如 record_transformer。如果沒有明確的轉換，這些物件會在緩衝區排清期間造成嚴重序列化錯誤。

如果設定使用 ${time} 和 enable_ruby true，您必須將物件明確轉換為原始型別、整數或字串。

以下是在舊版 Logging 代理程式中設定篩選器外掛程式的範例：

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time}
  </record>
</filter>

更新後，設定如下所示：

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time.to_i}
  </record>
</filter>

gRPC 傳輸和壓縮預設值

google_cloud 輸出外掛程式可讓您設定是否使用 gRPC，而非 REST/JSON 與 Cloud Logging API 通訊。

為提升效能，建議啟用 gRPC 傳輸並設定 grpc_compression_algorithm gzip。這種組合可將網路負擔和 CPU 耗用量降到最低，特別是在處理大量記錄時。

如要實作這些最佳化功能，請使用下列設定：

<match **>
  @type google_cloud
  use_grpc true
  grpc_compression_algorithm gzip
</match>

此外，由於 gRPC 依賴通訊埠 443 上的 HTTP/2 串流，因此您必須確保網路基礎架構允許 gRPC/HTTP/2 流量。在 gRPC 受到限制的環境中，您必須明確定義 use_grpc false，才能還原為標準 HTTP/REST 通訊。

RabbitMQ 規則運算式模式

舊版 Logging 代理程式用於擷取 RabbitMQ 記錄的規則運算式模式，通常與新版 RabbitMQ 的輸出格式不相容。這些差異可能會導致系統在收集記錄時處理錯誤，或直接捨棄記錄。

新版 RabbitMQ 記錄會在時間戳記中加入毫秒精確度，例如 YYYY-MM-DD HH:MM:SS.L，並提供特定嚴重程度和 PID 標記，例如 [info] <0.213.0>，而舊版規則運算式無法比對這些標記。

如果 Fluentd 代理程式已設定為收集 RabbitMQ 記錄，則必須更新 <parser> 區段，才能正確處理目前的記錄格式。

以下是舊版 Logging 代理程式的 RabbitMQ 輸入外掛程式設定範例：

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/lib/google-fluentd/pos/rabbitmq.pos
  tag rabbitmq
  format multiline
  format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/
  format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \[(?<severity>\w+)\] (?<message>.*)/
  time_format %Y-%m-%d %H:%M:%S
</source>

更新後，設定如下所示：

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/log/fluentd/pos/rabbitmq.pos
  read_from_head true
  tag rabbitmq
  <parse>
    @type multiline
    format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}/
    format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) \[(?<severity>[^\]]+)\] <(?<pid>[^>]+)> (?m:(?<message>.*))$/
    time_format %Y-%m-%d %H:%M:%S.%L
  </parse>
</source>