Announcing Telegraf 0.10.0

By Cameron Sparr / Product
Jan 12, 2016

Navigate to:

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]]

Input Configuration

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.

Examples

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 tag2=bar

[[inputs.cpu]]
  percpu = false
  totalcpu = true
  [inputs.cpu.tags]
    tag1 = "foo"
    tag2 = "bar"

Plugin Parallelization

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:

  • exec
  • httpjson
  • jolokia
  • postgresql
  • procstat
  • rabbitmq
  • twemproxy

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

Config File

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.

  • exec
  • httpjson
  • jolokia
  • postgresql
  • procstat
  • rabbitmq
  • twemproxy

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.

Additional Changes

View the changelog for a rundown of all changes made.