從舊版 Logging 代理程式遷移至上游 Fluentd

如果您使用舊版 Logging 代理程式，且有高度自訂的設定，建議遷移至開放原始碼的 Fluentd。您可以設定 Fluentd，保留 Logging 代理程式 環境的行為，同時不中斷 Cloud Logging 收集記錄。本文說明遷移程序。

功能比較

下表比較舊版 Logging 代理程式和上游 Fluentd 的主要功能。

功能與特色	舊版 Logging 代理程式	上游 Fluentd
將記錄擷取至 Cloud Logging	是	是
標準系統記錄 (syslog)	是	是
預先設定的第三方應用程式輸入內容	是	是 ^†
處理結構化 (JSON) 和非結構化 (文字) 記錄	是	是
合併多行例外狀況	是	是
Google Cloud 中繼資料充實	是	是
Kubernetes 中繼資料擴充功能	是	是
不重複的記錄項目 ID	是	是
記錄檔欄位轉換	是	是
嚴重性對應	是	是
驗證 (ADC 和服務帳戶金鑰)	是	是
REST 和 gRPC 傳輸通訊協定	是	是
監控整合	是	是

^†  雖然上游 Fluentd 和外掛程式的標準安裝中未包含 google-fluentd-catch-all- config 套件，但您可以按照本指南詳述的遷移步驟，維持預先設定的輸入功能。

事前準備

開始遷移前，請確認您具備以下項目：

• 支援的 VM 執行個體，位於Google Cloud 專案中。
• VM 執行個體上的憑證，可授權與 Cloud Logging 通訊。根據預設，Compute Engine VM 執行個體通常已配置正確憑證。如要確認您是否具備適當的憑證，請執行「授權記錄代理程式」程序。

遷移至 Fluentd

本節將說明如何遷移至上游 Fluentd 版本，同時維持舊版 Logging 代理程式提供的主要功能。

如要遷移設定，請完成下列步驟：

1. 關閉舊版 Logging 代理程式
2. 安裝穩定版 fluentd-package
3. 安裝 Google Cloud 平台外掛程式
4. 遷移輸入外掛程式設定檔
5. 更新系統記錄設定
6. 更新 Fluentd 設定檔
7. 確認 Fluentd 代理程式是否正常運作
8. 解除安裝舊版 Logging 代理程式

注意： 本節包含 Linux 指令範例。如果您使用 Windows，請根據該環境調整指令步驟。

關閉舊版 Logging 代理程式

安裝上游 Fluentd 代理程式前，請務必停止舊版 Logging 代理程式，以免發生衝突。為避免在遷移期間遺失任何待處理的記錄，請務必在關機時清除所有緩衝記錄。

如要正常關閉舊版 Logging 代理程式，請按照下列步驟操作：

1. 使用 SSH 或類似工具開啟 VM 執行個體的終端機連線，並確認您擁有 sudo 存取權。

2. 如要在關閉舊版 Logging 代理程式前排清所有緩衝記錄，請啟用 flush_at_shutdown 選項：

   1. 更新 /etc/google-fluentd/google-fluentd.conf 檔案，將 flush_at_shutdown 旗標設為 true：

      # Configure the agent to flush all buffer chunks on shutdown
      <match **>
        @type google_cloud
        flush_at_shutdown true
      </match>
      

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

      sudo service google-fluentd restart
      

3. 停止舊版 Logging 代理程式：

   sudo service google-fluentd stop
   

安裝穩定版 fluentd-package

在 VM 執行個體中安裝穩定版本的 Fluentd (fluentd-package)。如需操作說明，請參閱 Fluentd 安裝 fluent-package 說明文件。

安裝 Google Cloud 平台外掛程式

如要讓 Fluentd 與 Cloud Logging 互動，並處理特定記錄格式，請安裝下列外掛程式：

1. 如果尚未安裝，請安裝擴充功能編譯的建構工具：

   Debian 或 Ubuntu

   在 Debian 或 Ubuntu 上執行下列指令：

   sudo apt-get update
   sudo apt-get install -y build-essential
   

   CentOS 或 RHEL

   在 CentOS 或 RHEL 上執行下列指令：

   sudo yum update
   sudo yum groupinstall -y "Development Tools"
   

2. 安裝 fluent-plugin-google-cloud 外掛程式：

   sudo fluent-gem install fluent-plugin-google-cloud
   

3. 安裝 fluent-plugin-detect-exceptions 外掛程式：

   sudo fluent-gem install fluent-plugin-detect-exceptions
   

4. 選用：如果舊版 Logging 代理程式部署作業會從 Kubernetes 叢集內執行的應用程式收集記錄，請安裝 fluent-plugin-kubernetes_metadata_filter 外掛程式：

   sudo fluent-gem install fluent-plugin-kubernetes_metadata_filter
   

5. 選用：如果舊版 Logging 代理程式會以 Prometheus 格式收集及公開指標，請安裝下列 Gem：

   sudo fluent-gem install prometheus-client -v 0.9.0
   sudo fluent-gem install fluent-plugin-prometheus -v 1.4.0
   

   警告： 0.10.0 以上版本的 prometheus-client 不相容，會導致 Fluentd 在啟動時當機。

遷移輸入外掛程式設定檔

如要遷移現有的 Fluentd 安裝設定和位置檔案，請完成下列步驟：

1. 為 Fluentd 設定和位置檔案建立目錄：

   # Create the destination directory for Fluentd configuration files
   sudo mkdir -p /etc/fluent/config.d
   
   # Create the destination directory for position files
   sudo mkdir -p /var/lib/fluent/pos
   

2. 將 google-fluentd 設定檔複製到 Fluentd 的設定目錄：

   sudo cp /etc/google-fluentd/config.d/* /etc/fluent/config.d/
   

3. 將 google-fluentd 使用的所有位置 (.pos) 檔案複製到 Fluentd 的 position-file 目錄：

   sudo cp /var/lib/google-fluentd/pos/*.pos /var/lib/fluent/pos/
   

   位置檔案用於追蹤記錄檔中的讀取位置。遷移這些檔案後，Fluentd 就能從 google-fluentd 使用的相同位置開始。

4. 更新新 Fluentd 設定檔中的 pos_file 路徑，指向新的位置檔案目錄：

   sudo sed -i 's#/var/lib/google-fluentd#/var/lib/fluent#g' /etc/fluent/config.d/*.conf
   

5. 授予 Fluentd 服務使用者「_fluentd」對「/var/lib/fluent/」目錄的讀寫權限：

   sudo chown -R _fluentd:_fluentd /var/lib/fluent/
   

6. 授予 _fluentd 使用者 syslog 檔案的讀取權限：

   sudo usermod -a -G adm _fluentd
   

更新系統記錄設定

上游 Fluentd 會以無權限使用者身分執行，無法繫結至編號小於 1024 的權限通訊埠。如果舊版 Logging 代理程式設定包含使用 @type syslog 的網路型系統記錄收集功能，您必須調整設定。port 514

如要更新通訊埠設定，請按照下列步驟操作：

1. 將 /etc/fluent/config.d/syslog_endpoint.conf 檔案的全部內容替換為下列設定：

   sudo tee /etc/fluent/config.d/syslog_endpoint.conf > /dev/null <<EOF
   <source>
     @type syslog
     port 5140
     <transport tcp>
     </transport>
     bind 127.0.0.1
     tag syslog
   </source>
   EOF
   

2. 建立或修改 /etc/rsyslog.d/40-fluentd-forward.conf 檔案，將系統記錄訊息轉送至新的 Fluentd 連接埠：

   sudo tee /etc/rsyslog.d/40-fluentd-forward.conf > /dev/null <<EOF
   # Forward all syslog messages to Fluentd on localhost:5140 via TCP
   *.* @@127.0.0.1:5140
   EOF
   

3. 重新啟動 rsyslog 服務，以套用變更：

   sudo systemctl restart rsyslog.service
   

更新主要的 Fluentd 設定檔

從代理程式的設定檔 google-fluentd.conf 複製設定，然後貼到位於 /etc/fluent/fluentd.conf 的主要 Fluentd 設定檔，即可設定上游 Fluentd 代理程式。

注意： 安裝 Google 外掛程式後，上游版本的 Fluentd 即可支援舊版 Logging 代理程式的所有功能。詳情請參閱「設定 Logging 代理程式」。

如要設定上游 Fluentd 代理程式，請完成下列步驟：

1. 複製 google-fluentd.conf 檔案的完整內容，覆寫預設上游 Fluentd 設定檔：

   sudo cp /etc/google-fluentd/google-fluentd.conf /etc/fluent/fluentd.conf
   

2. 更新 Fluentd 設定檔中的 buffer_path，指向新的 Fluentd 目錄：

   sudo sed -i 's#/var/log/google-fluentd#/var/log/fluent#g' /etc/fluent/fluentd.conf
   

3. 檢查 fluentd.conf 檔案，確認設定包含下列項目：

   • @include config.d/*.conf，即可匯入所有輸入外掛程式設定。
   • <match **> @type google_cloud 區塊已設定為將記錄串流至 Cloud Logging。
   • 輸出外掛程式中的 buffer_path 現在會指向 /var/lib/fluent/。
   • 輸入外掛程式中的任何 pos_file 指令都會指向 /var/lib/fluent/。

4. 執行模擬測試，驗證 Fluentd 設定：

   sudo fluentd -c /etc/fluent/fluentd.conf --dry-run
   

   檢查輸出結果是否有任何 error 或 warn 快訊。您必須先解決所有已發現的問題，才能繼續操作。如要瞭解語法變更的詳細資料，請參閱「上游 Fluentd 的設定相容性」。

5. 重新啟動 Fluentd 代理程式：

   sudo service fluentd restart
   

確認 Fluentd 代理程式是否正常運作

啟動 Fluentd 後，請確認記錄已順利傳送至 Cloud Logging：

1. 確認 Fluentd 執行時未發生錯誤：

   $ sudo service fluentd status
   

   服務狀態應為有效 (執行中)。

2. 檢查 Fluentd 記錄，確認沒有錯誤或警告：

   sudo tail -n 100 /var/log/fluent/fluentd.log | grep -iE "error|warn|failed|exception" || true
   

   不應列出任何錯誤或警告。

3. 查看 Cloud Logging，確認是否收到 VM 執行個體的記錄。如要瞭解如何查看記錄，請參閱「使用 Logs Explorer」。

解除安裝舊版 Logging 代理程式

確認新的 Fluentd 成功將記錄傳送至 Cloud Logging 後，再移除舊版 Logging 代理程式及其設定檔：

Debian 或 Ubuntu

  sudo apt-get remove --purge google-fluentd

CentOS 或 RHEL

  sudo yum remove google-fluentd