This article explains how to manage Fluentd plugins, including adding 3rd party plugins.
fluent-gem command is used to install Fluentd plugins. This is a wrapper around the
fluent-gem install fluent-plugin-grep
Ruby doesn't guarantee C extension API compatibility between its major versions. If you update Fluentd's Ruby version, you should re-install the plugins that depend on C extension.
If you are using td-agent, please make sure to use td-agent's
td-agent-gem command. td-agent has own Ruby so you should install gems into td-agent's Ruby, not other Ruby. Otherwise (e.g. you use the command belonging to system, rvm, etc.), you won't be able to find your "installed" plugins.
Some plugins depend on natvie extension library. It means you need to install development packages to build it, e.g. gcc, make, autoconf and etc. If you see logs like below, install development packages before plugin installation.
Building native extensions. This could take a while...ERROR: Error installing fluent-plugin-twitter:ERROR: Failed to build gem native extension./opt/td-agent/embedded/bin/ruby extconf.rbchecking for rb_str_scrub()... yescreating Makefilemake "DESTDIR = " cleansh: 1: make: not foundmake "DESTDIR = "sh: 1: make: not foundmake failed, exit code 127Gem files will remain installed in /opt/td-agent/embedded/lib/ruby/gems/2.1.0/gems/string-scrub-0.0.3 for inspection.Results logged to /opt/td-agent/embedded/lib/ruby/gems/2.1.0/extensions/x86_64-linux/2.1.0/string-scrub-0.0.3/gem_make.out
-p option is used to add an extra plugin directory to the load path. For example, if you put the
out_foo.rb plugin into
/path/to/plugin, you can load the
out_foo.rb plugin by specifying the
-p option as shown below.
fluentd -p /path/to/plugin
You can specify the
-p option more than once.
Fluentd adds the
/etc/fluent/plugin directory to its load path by default. Thus, any additional plugins that are placed in
/etc/fluent/plugin will be loaded automatically.
If you are using td-agent, Fluentd uses the
/etc/td-agent/plugin directory instead of
/etc/fluent/plugin. Please put your plugins here instead.
Fluentd and plugins are evolving, so you may hit unexpected error with latest version, e.g. regression by new feature, remove deprecated parameter, change library dependency, etc. To avoid these problems, we recommend to fix fluentd and plugin version on production. If you want to update fluentd or plugins, check the behaviour first on your test environment. For example, td-agent fixes fluentd and plugins version in each release.
Fluentd plugins are rubygems and rubygems installs latest version by default. So we don't recommend to execute following commands on production:
gem install fluentd
gem install fluent-plugin-elasticsearch
gem update # This is very dangerous. Update all existing gems
You should specify target version with
gem install fluentd -v 1.2.1
gem install fluent-plugin-elasticsearch -v 2.10.3
A Ruby application manages gem dependencies using Gemfile and Bundler. Fluentd's
--gemfile option takes the same approach, and is useful for managing plugin versions separated from shared gems.
For example, if you have following Gemfile at /etc/fluent/Gemfile:
source 'https://rubygems.org'gem 'fluentd', '1.2.1'gem 'fluent-plugin-elasticsearch', '2.10.3'
You can pass this Gemfile to Fluentd via the
fluentd --gemfile /etc/fluent/Gemfile
When specifying the
--gemfile option, Fluentd will try to install the listed gems using Bundler. Fluentd will only load listed gems separated from shared gems, and will also prevent unexpected plugin updates.
In addition, if you update Fluentd's Ruby version, Bundler will re-install the listed gems for the new Ruby version. This allows you to avoid the C extension API compatibility problem.
We can manage Fluentd and its plugins based on Gemfile with td-agent.
Use following drop-in file /etc/systemd/system/td-agent.service.d/override.conf for td-agent 3.1.1:
[Service]Environment='TD_AGENT_OPTIONS=--gemfile=/etc/td-agent/Gemfile --gem-path=/var/lib/td-agent/vendor/bundle'ExecStart=ExecStart=/opt/td-agent/embedded/bin/fluentd --log /var/log/td-agent/td-agent.log --daemon /var/run/td-agent/td-agent.pid $TD_AGENT_OPTIONS
We can also edit this file by following command:
$ sudo systemctl edit td-agent.service
And then add /etc/td-agent/Gemfile:
source "https://rubygems.org"# You can use fixed version of Fluentd and its pluginsgem "fluentd", "1.2.1"gem "fluent-plugin-elasticsearch", "2.4.0"gem "fluent-plugin-kafka", "0.6.5"gem "fluent-plugin-rewrite-tag-filter", "2.0.1"gem "fluent-plugin-s3", "1.1.0"gem "fluent-plugin-td", "1.0.0"gem "fluent-plugin-td-monitoring", "0.2.3"gem "fluent-plugin-webhdfs", "1.2.2"# Add plugins you want to usegem "fluent-plugin-geoip", "1.2.0"
Finally, restart td-agent:
$ sudo systemctl restart td-agent.service
NOTE: In this approach, you will download all gems listed in Gemfile even if td-agent includes them at the first time.
The latest version is used. If command shows following result:
$ fluent-gem list...skip...fluent-plugin-record-modifier (2.0.1, 0.6.0, 0.5.0)
2.0.1 version is used.
If this article is incorrect or outdated, or omits critical information, please let us know. Fluentd is a open source project under Cloud Native Computing Foundation (CNCF). All components are available under the Apache 2 License.