Today we are officially releasing Telegraf 0.10.0. Going forward, all InfluxData products under the same major release will be guaranteed compatible with one another, and thus Telegraf is jumping forward to 0.10.x to coincide with the upcoming 0.10.0 InfluxDB release (late-January).
Release 0.10.0 brings a raft of new changes and improvements, many of which are breaking changes. There are a few reasons why we are making a breaking release, which I’ll go over below. See the end of this blog post for a guide on migrating from Telegraf 0.2.x to 0.10.0.
Fields instead of measurements
Telegraf previously put almost every metric it collected into a single measurement with a single field called `value`, ie, `cpu_usage_idle value=100`, `cpu_usage_guest value=0`. Going forward, Telegraf will (for the most part) put all plugins into a single measurement with a field for each metric, ie, `cpu usage_guest=0,usage_idle=100`. This has many benefits, one of which is that users can easily make math queries on relationships between different metrics within a plugin. For example, with the memory plugin, you can calculate the percent of total memory buffered like this:
`SELECT buffered/total FROM mem`
Another considerable benefit is that this will reduce the amount of network traffic that each Telegraf instance generates. The reason for this is primarily that timestamps and tags are now only sent once for each plugin, rather than once for each measurement. The reduction that you see will depend on which plugins you use, but most users can expect at least a 50% reduction in network traffic.
Renaming plugins -> inputs
Telegraf began as an agent for collecting metrics from plugins and writing them into InfluxDB. Naturally, the input plugins were simply called “plugins”. Telegraf, however, has outgrown this name, since we now have “output plugins” in addition to “input plugins”. There are also plans for the future to have things like “aggregator plugins” and “filter plugins”. For this reason, we are renaming “plugins” to “inputs”, and restructuring where they appear in the repo. Inputs and Outputs are now both under the plugins/ directory in the root repo. This also means that the config for each input has changed from `[[plugins.cpu]]` to `[[inputs.cpu]]`
For 0.10.0 there are a few new input configuration options:
- name_override: Override the base name of the measurement. (Default is the name of the plugin).
- name_prefix: Specifies a prefix to attach to the measurement name.
- name_suffix: Specifies a suffix to attach to the measurement name.
- tags: A map of tags to apply to a specific input’s measurements.
This plugin will emit measurements with the name `cpu_total` instead of only `cpu`
[[inputs.cpu]] name_suffix = "_total" percpu = false totalcpu = true
This will emit measurements with the name `foobar` instead of `cpu`
[[inputs.cpu]] name_override = "foobar" percpu = false totalcpu = true
This plugin will emit measurements with two additional tags: `tag1=foo` and
[[inputs.cpu]] percpu = false totalcpu = true [inputs.cpu.tags] tag1 = "foo" tag2 = "bar"
Over the past 9 months, Telegraf has added a lot of new functionality, and some of that didn’t really fit into the way that Telegraf was structured and organized. As time progressed, it became clear that we would need to create an avenue for multiple instances of the same plugin to run.
Many contributors solved this problem by setting up internal configuration lists and threads. Take the exec plugin, which was originally configured like this:
# telegraf.conf [inputs.exec] # specify commands via an array of tables [[inputs.exec.commands]] # the command to run command = "/usr/bin/mycollector --foo=bar" # name of the command (used as a prefix for measurements) name = "mycollector" # Only run this command if it has been at least this many # seconds since it last ran interval = 10 [[inputs.exec.commands]] command = "/usr/bin/othercollector" name = "othercollector" interval = 15
This is a good solution, and allows users of the `exec` plugin to specify multiple binaries to be executed. But there are some problems here. Since each `exec.command` is defined within the plugin, it does not have access to Telegraf’s general plugin configuration options. The `interval` parameter that you see above is a custom implementation specific to the `exec` plugin. Another problem is that it requires the plugin writer to internally handle threading and errors, when that
functionality is already builtin to the Telegraf agent.
So going forward, this internal threading has largely been removed from inputs that were using it. Instead, users can now define inputs as lists, allowing the above configuration to change to this:
# telegraf.conf [[inputs.exec]] # the command to run command = "/usr/bin/mycollector --foo=bar" # name_prefix is a new parameter in 0.10.0 available to all inputs name_prefix = "mycollector_" # This is the general interval parameter available to all inputs. interval = "10s" [[inputs.exec]] command = "/usr/bin/othercollector" name_prefix = "othercollector_" interval = "15s"
This also means, unfortunately, that users of these inputs will need to rewrite their configuration to work with Telegraf 0.10.0. Use `telegraf -sample-config` to see examples of the new config for your particular input.
The following inputs are affected by this change:
Linux package moving out of `/opt`
By popular demand, we are moving away from using the `opt` directory for
Telegraf (as we’ve already done with InfluxDB and Kapacitor).
Below is a summary of the linux package changes:
- Binaries are now located at `/usr/bin/`
- Configuration is now located at `/etc/telegraf`
- A few fixes and updates to the `init.sh` script
- Minor update to the `telegraf.service` unit file to correct usage of variable
- Added a `post-install.sh` and `pre-install.sh` to handle upgrades and other housekeeping
Migrating from Telegraf 0.2.x
If you are currently using Telegraf 0.2.x, you should start by installing version 0.10.0 and generating a new config file:
`$ telegraf -sample-config > /tmp/test.0.10.0.conf`
Open the file in the editor of your choice and find the plugins that you wish to configure. Inspect the differences between the old and new configuration and merge the new config with yours. Make sure you rename `plugin` -> `input`. Most plugins will have identical configuration options, but some are substantially different. The following plugins have substantially different configurations.
If you need additional help configuring these, please refer to the Plugin Parallelization section above, and see the changelog.
Fields Instead of Measurements
When you start using Telegraf 0.10.0, you will notice that your previous measurements will no longer be getting new metrics. This is because almost all plugins have changed to report metrics as multiple fields on a single measurement.
To get an idea of the change, try running telegraf in test mode in both versions:
# Telegraf 0.2.x $ telegraf -config /etc/opt/telegraf/telegraf.conf -test
# Telegraf 0.10.0 $ telegraf -config /etc/telegraf/telegraf.conf -test
And compare the output, you should see that there are less measurements but more fields. The `mem` plugin, for example, used to report all metrics as their own measurements (ie, `mem_free`, `mem_used`, `mem_buffered`). So querying your buffered memory from influxdb would look like this:
# Telegraf 0.2.x SELECT value FROM mem_buffered
As of Telegraf 0.10.0, the plugin will report a single measurement called `mem`, with fields for each metric. So querying your buffered memory from influxdb now looks like this:
# Telegraf 0.10.0 SELECT buffered FROM mem
You will need to change these queries in your InfluxDB instrumentation and clients. For more information on the differences between fields, measurements, and tags, see the docs.
View the changelog for a rundown of all changes made.