ククログ

株式会社クリアコード > ククログ > Fluentd v1.15.0リリース -- YAML形式サポートなどの新機能とin_tailの不具合修正

Fluentd v1.15.0リリース -- YAML形式サポートなどの新機能とin_tailの不具合修正

2022年6月29日にFluentdの最新版となるv1.15.0をリリースしました。

クリアコードはFluentdの開発に参加し、リリースを含めたメンテナンス作業を行っています。

今回はv1.15.0で追加された新機能を中心に紹介します。

Fluentd v1.15.0の新機能

YAML形式の設定をサポート

Fluentdの設定ファイルは、Apacheのhttpd.confの形式を模して、ディレクティブから成る形式を用いていました。

一方で以前から、YAMLやJSONなどのより一般的な形式を使いたいという声も挙がっていました。

本バージョンから、Kubernetesとの親和性を考慮して、YAML形式の設定ファイルも使用できるようになりました。詳細は公式ドキュメント1の通りですが、ここではチュートリアル形式で主要なポイントをご紹介します。

1: シンプルな設定と実行

in_sampleプラグイン2でサンプルデータを発生させ、out_stdoutプラグインで標準出力に出力させるシンプルな設定です。

config:
  - source:
      $type: sample
      tag: test.log
  - match:
      $type: stdout
      $tag: test.**

ポイントは次です。

  • config:の配下にsourceなどの各設定を並べます。
  • sourcematchなどの各項目は-をつけます3
  • sourcematchの内部の各パラメータ設定は、インデントを1つ深くします4
  • @typeの代わりに$typeを用います。
  • ディレクティブで指定していたタグは、$tagで指定します5
    • in_sampletagはプラグインの通常のパラメータなので$が付きません。

この設定をfluent.yamlのようなファイルに保存し、次のようにfluentdを起動することで使用できます。拡張子がyamlymlであれば、Fluentdが自動でyaml形式と認識します。

$ bundle exec fluentd -c fluent.yaml

2: labelの設定と注意するべき記号

filter_record_transformerプラグイン6を使い、{"label": "Test"}というデータを付与した上で標準出力する処理を@testという名前のlabelとして設定します7in_sampleプラグインを1つ増やし、メッセージをカスタマイズした上でそのlabelに流します。

config:
  - source:
      $type: sample
      tag: test.log
  - source:
      $type: sample
      $label: "@test"
      tag: test.log
      sample: "{\"message\": \"Sample for the test-label\"}"

  - match:
      $type: stdout
      $tag: test.**

  - label:
      $name: "@test"
      config:
        - filter:
            $type: record_transformer
            $tag: "**"
            record:
              label: Test
        - match:
            $type: stdout
            $tag: "**"

この設定は次のように、labelを流れないログとlabelに流れたログの双方を出力します。

{datetime} test.log: {"message":"sample"}
{datetime} test.log: {"message":"sample for the test-label","label":"Test"}

ポイントは次です。

  • @labelではなくて$labelを用います。
  • labelディレクティブで指定していたラベル名は、$nameで指定します。
  • labelの下にconfigを挟みます8
  • 単語先頭の@*はYAML形式の予約語なので、必ずクオーテーションで囲います。
  • 従来の形式ではsample: {"message": "Sample for the test-label"}のようにそのまま記載できましたが、YAMLでは全体をクオーテーションで囲い、内部のクオーテーションをエスケープします。

3: マルチワーカーの設定とRubyコードの埋め込み

system設定9を行い、4つのワーカーで動作させるようにします。さらに一部は特定のワーカーで動作するように指定します10。またRubyコード#{worker_id}を埋め込み、動作したワーカーのidを出力データに追加します。

system:
  workers: 4

config:
  - source:
      $type: sample
      tag: test.allworkers
      sample: "{\"message\": \"Run with all workers.\"}"

  - worker:
      $arg: 0
      config:
        - source:
            $type: sample
            tag: test.oneworker
            sample: "{\"message\": \"Run with only worker-0.\"}"

  - worker:
      $arg: 0-1
      config:
        - source:
            $type: sample
            tag: test.someworkers
            sample: "{\"message\": \"Run with worker-0 and worker-1.\"}"

  - filter:
      $type: record_transformer
      $tag: test.**
      record:
        worker_id: !fluent/s "#{worker_id}"

  - match:
      $type: stdout
      $tag: test.**

この設定で出力される次のログを見ると、想定したworkerでそれぞれのin_sampleが動作していることが分かります。

{datetime} test.allworkers: {"message":"Run with all workers.","worker_id":"0"}
{datetime} test.allworkers: {"message":"Run with all workers.","worker_id":"1"}
{datetime} test.allworkers: {"message":"Run with all workers.","worker_id":"2"}
{datetime} test.allworkers: {"message":"Run with all workers.","worker_id":"3"}
{datetime} test.oneworker: {"message":"Run with only worker-0.","worker_id":"0"}
{datetime} test.someworkers: {"message":"Run with worker-0 and worker-1.","worker_id":"0"}
{datetime} test.someworkers: {"message":"Run with worker-0 and worker-1.","worker_id":"1"}

ポイントは次です。

  • system設定はconfigとは別に設定します。
  • workerディレクティブで指定していたワーカーidは、$argで指定します。
  • Rubyコードの埋め込みを行うには、!fluent/sを付ける必要があります。

YAML形式設定のまとめ

以上3例についてポイントを見てきました。

ここまで理解できれば、大抵の使い方はできるはずです。

従来の@includeに相当する!includeなど、ここでは説明しきれない設定もありますので、より詳しい使い方については公式ドキュメント1を参考にしてください。

in_tail: 詳細な流量制限を可能にするgroupオプションを追加

in_tailプラグイン11に、新しいオプションとしてgroupディレクティブを追加しました。

in_tailプラグインはログファイルのデータ収集によく使われますが、一つのファイルでログが大量発生するとその処理にかかりっきりになり、他のファイルの処理が行われない点が問題でした。

この問題の対策として、read_bytes_limit_per_secondオプション12をv1.13.0で追加し、流量を制限できるようになっていました。

しかし、これはユーザーにとって重要なログもそうでないログも一様に流量を制限してしまう、という問題が残っていました。

そこで今回、このgroupオプションを追加し、重要度に応じてファイル単位で細かな流量制限を行うことができるようになりました。

詳しい使い方は、次の公式ドキュメントをご覧ください。

system: ワーカーの停止期間を設定するrestart_worker_intervalオプションを追加

systemディレクティブに、新しいオプションrestart_worker_intervalを追加しました。

ワーカープロセスがエラーやkillコマンド等で停止すると、Fluentdは即座にそのワーカープロセスをリスタートします13

しかし、意図的にワーカープロセスにしばらく停止してほしいというケースが、一部のユーザーから報告されていました。

今回この新しいオプションを設定することで、設定した期間ワーカープロセスのリスタートを待機させることができます。

リスタートまで1分間待機させる設定例:

<system>
  restart_worker_interval 1m
</system>

time型の値を取るため、1時間なら1hのようにも設定できます。

fluent-ctl: デバッグ用にFluentdの内部情報を出力させるdumpコマンドを追加

fluent-ctl14は、設定のリロードなどFluentdを操作するために使えるツールです。

用途に応じていくつかのコマンドを利用できますが、今回新しくdumpコマンドを追加しました。

従来から、非Windows環境(UNIX系OSの環境)であれば、SIGCONTシグナルを対象プロセスに送信することで、Fluentdにデバッグ用の内部情報を出力させることができました15。しかし、Windows環境ではシグナルを使うことができないため、内部情報を出力させる方法がありませんでした。

これを使うことで、Windows環境でもFluentdにデバッグ用の内部情報を出力させられるようになります。

次のように使うことができます。

$ fluent-ctl dump [PID_OR_SVCNAME]

FluentdをWindows Serviceとして動作させている場合は、Service名を指定します。ただし、デフォルトのService名fluentdwinsvcのままであれば省略可能です。

Serviceとして動作させていない場合は、Supervisorプロセスのプロセスidを指定してください。

実行すると、システムの一時フォルダであるC:\\Windows\\Temp配下にプロセス毎にファイルが出力されます。

詳しくは次の公式ドキュメントをご覧ください。

その他

in_tail関連の不具合を何点か修正しているので、より安定して使えるようになっています。

新しい機能を使う予定がなくても、アップグレードをお勧めします。

詳しくは、冒頭で紹介したリリースアナウンスページをご覧ください。

まとめ

今回の記事では、Fluentd v1.15.0について最新情報をお届けしました。

最新版を使ってみて、何か気になる点があればぜひGitHubで開発チームまでフィードバックをお寄せください!

  1. https://docs.fluentd.org/configuration/config-file-yaml

  2. https://docs.fluentd.org/input/sample

  3. これらはいくつでも並べられる項目であり、YAMLのリスト形式になります。

  4. 間違いやすいポイントです。次のようにハッシュの二重構造になっています: {"source": {"$type": "sample", "tag": "test,log"}}

  5. ディレクティブを用いない形式のため、 <match test.**>test.** のように指定していたタグ等の値をパラメタとして指定する必要があります。同様のものに、後述する$arg$nameがあります。

  6. https://docs.fluentd.org/filter/record_transformer

  7. https://docs.fluentd.org/configuration/routing-examples#with-label-input-greater-than-filter-greater-than-output

  8. 後述するworkerディレクティブなど独立した設定の塊を定義するものは、このように再度configを挟み込みます。

  9. https://docs.fluentd.org/deployment/system-config

  10. https://docs.fluentd.org/deployment/multi-process-workers

  11. https://docs.fluentd.org/input/tail

  12. https://docs.fluentd.org/input/tail#read_bytes_limit_per_second

  13. 厳密にはFluentdのSupervisorプロセスがワーカープロセスのリスタートを試みます。

  14. https://docs.fluentd.org/deployment/command-line-option#fluent-ctl

  15. https://docs.fluentd.org/deployment/trouble-shooting#dump-fluentds-internal-information