以前の Logging エージェントからアップストリーム Fluentd に移行する

以前の Logging エージェントを使用していて、構成を大幅にカスタマイズしている場合は、オープンソースの Fluentd に移行することをおすすめします。Cloud Logging によるログの収集を中断することなく、Logging エージェント環境の動作を維持するように Fluentd を構成できます。このドキュメントでは、移行プロセスについて説明します。

機能の比較

次の表に、以前の Logging エージェントとアップストリーム Fluentd の主な機能のパリティ比較を示します。

機能	以前の Logging エージェント	アップストリーム Fluentd
Cloud Logging へのログの取り込み	はい	はい
標準のシステムログ（syslog）	はい	はい
事前構成済みのサードパーティ アプリケーション入力	はい	はい ^†
構造化（JSON）ログと非構造化（テキスト）ログの処理	はい	はい
複数行の例外のマージ	はい	はい
Google Cloud メタデータの拡充	はい	はい
Kubernetes メタデータの拡充	はい	はい
一意のログエントリ ID	はい	はい
ログフィールドの変換	はい	はい
重大度のマッピング	はい	はい
認証（ADC とサービス アカウント キー）	はい	はい
REST と gRPC のトランスポート プロトコル	はい	はい
モニタリングの統合	はい	はい

^†  google-fluentd-catch-all-config パッケージは、アップストリームの Fluentd とプラグインの標準インストールには含まれていませんが、このガイドで説明する移行手順に沿って、事前構成済みの入力機能を維持できます。

始める前に

移行を開始する前に、次のものが揃っていることを確認してください。

• Google Cloud プロジェクトでサポートされている VM インスタンス。
• Cloud Logging との通信を承認する VM インスタンス上の認証情報。通常、Compute Engine VM インスタンスにはデフォルトで適切な認証情報があります。適切な認証情報があるかどうかを確認するには、Logging エージェントを認可するの手順を実施します。

Fluentd に移行する

このセクションでは、以前の Logging エージェントが提供する主な機能を維持しながら、アップストリームの Fluentd バージョンに移行する手順について説明します。

設定を移行する手順は次のとおりです。

1. 以前の Logging エージェントをシャットダウンする
2. fluentd-package の安定版をインストールする
3. Google Cloud プラットフォーム プラグインをインストールする
4. 入力プラグインの構成ファイルを移行する
5. syslog 構成を更新する
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/
   

   位置ファイルは、ログファイルの読み取り位置を追跡するために使用されます。移行すると、google-fluentd が使用していたのと同じポイントから 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
   

syslog 構成を更新する

アップストリームの Fluentd は権限のないユーザーとして実行されるため、1024 未満の特権ポートにバインドできません。レガシーの Logging エージェントの設定に、port 514 で @type syslog を使用したネットワーク ベースの syslog 収集が含まれている場合は、構成を調整する必要があります。

ポート構成を更新する手順は次のとおりです。

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 ファイルを作成または変更して、syslog メッセージを新しい 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 インスタンスからログが受信されていることを確認します。ログの表示については、ログ エクスプローラの使用をご覧ください。

以前の Logging エージェントをアンインストールする

新しい Fluentd が Cloud Logging にログを正常に送信していることを確認してから、以前の Logging エージェントとその構成ファイルを削除します。

Debian または Ubuntu

  sudo apt-get remove --purge google-fluentd

CentOS または RHEL

  sudo yum remove google-fluentd