Telegraf Contents

Configuration

This is archived documentation for InfluxData product versions that are no longer maintained. For newer documentation, see the latest InfluxData documentation.

Generating a Configuration File

A default Telegraf config file can be generated using the -sample-config flag:

telegraf -sample-config > telegraf.conf

To generate a file with specific inputs and outputs, you can use the -input-filter and -output-filter flags:

telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka

You can see the latest config file with all available plugins here: telegraf.conf.

Environment Variables

Environment variables can be used anywhere in the config file, simply prepend them with $. For strings the variable must be within quotes (ie, "$STR_VAR"), for numbers and booleans they should be plain (ie, $INT_VAR, $BOOL_VAR)

[global_tags] Configuration

Global tags can be specified in the [global_tags] section of the config file in key=“value” format. All metrics being gathered on this host will be tagged with the tags specified here.

[agent] Configuration

Telegraf has a few options you can configure under the agent section of the config.

  • interval: Default data collection interval for all inputs
  • round_interval: Rounds collection interval to interval ie, if interval="10s" then always collect on :00, :10, :20, etc.
  • metric_batch_size: Telegraf will output collected metrics in batches no larger than metric_batch_size .
  • metric_buffer_limit: Telegraf will cache metrics for each output up to the metric_buffer_limit and flushes the buffer on a successful write. If the bugger fills, the oldest metrics are dropped first. Raising this value increases the tolerance for connectivity outages but will also raise the potential memory footprint for Telegraf. This setting should be a multiple of metric_batch_size and must not be less than 2 times metric_batch_size.
  • collection_jitter: Jitter the collection time by a random amount. Each plugin will sleep for a random time less than collection_jitter before collecting. This can be used to avoid multiple plugins querying things like sysfs at the same time, which can have a measurable effect on the system.
  • flush_interval: Default data flushing interval for all outputs. You should not set this below interval. The maximum time before data is flushed to output is flush_interval + flush_jitter
  • flush_jitter: Jitter the flush interval by a random amount. This is primarily to avoid large write spikes when running a large number of telegraf instances. e.g., jitter=5s and flush_interval=10s means flushes will happen every 10-15 seconds.
  • debug: Run telegraf in debug mode.
  • quiet: Run telegraf in quiet mode.
  • hostname: Override default hostname, if empty use os.Hostname().

Measurement Filtering

Filters can be configured per input or output, see below for examples.

  • namepass: An array of strings that is used to filter metrics generated by the current input. Each string in the array is tested as a glob match against measurement names and if it matches, the field is emitted.
  • namedrop: The inverse of pass, if a measurement name matches, it is not emitted.
  • fieldpass: An array of strings that is used to filter metrics generated by the current input. Each string in the array is tested as a glob match against field names and if it matches, the field is emitted. fieldpass is not available for outputs.
  • fielddrop: The inverse of pass, if a field name matches, it is not emitted. fielddrop is not available for outputs.
  • tagpass: tag names and arrays of strings that are used to filter measurements by the current input. Each string in the array is tested as a glob match against the tag name, and if it matches the measurement is emitted.
  • tagdrop: The inverse of tagpass. If a tag matches, the measurement is not emitted. This is tested on measurements that have passed the tagpass test.
  • tagexclude: tagexclude can be used to exclude a tag from measurement(s). As opposed to tagdrop, which will drop an entire measurement based on it’s tags, tagexclude simply strips the given tag keys from the measurement. This can be used on inputs & outputs, but it is recommended to be used on inputs, as it is more efficient to filter out tags at the ingestion point.
  • taginclude: taginclude is the inverse of tagexclude. It will only include the tag keys in the final measurement.

NOTE: The tagpass and tagdrop parameters must be defined at the end of the plugin definition, otherwise subsequent plugin config options will be interpreted as part of the tagpass/tagdrop map.

Input Configuration

Some configuration options are configurable per input:

  • name_override: Override the base name of the measurement. (Default is the name of the input).
  • 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.
  • interval: How often to gather this metric. Normal plugins use a single global interval, but if one particular input should be run less or more often, you can configure that here.

Input Configuration Examples

This is a full working config that will output CPU data to an InfluxDB instance at 192.168.59.103:8086, tagging measurements with dc=“denver-1”. It will output measurements at a 10s interval and will collect per-cpu data, dropping any fields which begin with time_.

[global_tags]
  dc = "denver-1"

[agent]
  interval = "10s"

# OUTPUTS
[[outputs.influxdb]]
  url = "http://192.168.59.103:8086" # required.
  database = "telegraf" # required.
  precision = "s"

# INPUTS
[[inputs.cpu]]
  percpu = true
  totalcpu = false
  # filter all fields beginning with 'time_'
  fielddrop = ["time_*"]

Input Config: tagpass and tagdrop

NOTE: The tagpass and tagdrop parameters must be defined at the end of the plugin definition, otherwise subsequent plugin config options will be interpreted as part of the tagpass/tagdrop map.

[[inputs.cpu]]
  percpu = true
  totalcpu = false
  fielddrop = ["cpu_time"]
  # Don't collect CPU data for cpu6 & cpu7
  [inputs.cpu.tagdrop]
    cpu = [ "cpu6", "cpu7" ]

[[inputs.disk]]
  [inputs.disk.tagpass]
    # tagpass conditions are OR, not AND.
    # If the (filesystem is ext4 or xfs) OR (the path is /opt or /home)
    # then the metric passes
    fstype = [ "ext4", "xfs" ]
    # Globs can also be used on the tag values
    path = [ "/opt", "/home*" ]

Input Config: fieldpass and fielddrop

# Drop all metrics for guest & steal CPU usage
[[inputs.cpu]]
  percpu = false
  totalcpu = true
  fielddrop = ["usage_guest", "usage_steal"]

# Only store inode related metrics for disks
[[inputs.disk]]
  fieldpass = ["inodes*"]

Input Config: namepass and namedrop

# Drop all metrics about containers for kubelet
[[inputs.prometheus]]
  urls = ["http://kube-node-1:4194/metrics"]
  namedrop = ["container_*"]

# Only store rest client related metrics for kubelet
[[inputs.prometheus]]
  urls = ["http://kube-node-1:4194/metrics"]
  namepass = ["rest_client_*"]

Input Config: taginclude and tagexclude

# Only include the "cpu" tag in the measurements for the cpu plugin.
[[inputs.cpu]]
  percpu = true
  totalcpu = true
  taginclude = ["cpu"]

# Exclude the "fstype" tag from the measurements for the disk plugin.
[[inputs.disk]]
  tagexclude = ["fstype"]

Input config: prefix, suffix, and override

This plugin will emit measurements with the name cpu_total

[[inputs.cpu]]
  name_suffix = "_total"
  percpu = false
  totalcpu = true

This will emit measurements with the name foobar

[[inputs.cpu]]
  name_override = "foobar"
  percpu = false
  totalcpu = true

Input config: tags

This plugin will emit measurements with two additional tags: tag1=foo and tag2=bar

NOTE: Order matters, the [inputs.cpu.tags] table must be at the end of the plugin definition.

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

Multiple inputs of the same type

Additional inputs (or outputs) of the same type can be specified, just define more instances in the config file. It is highly recommended that you utilize name_override, name_prefix, or name_suffix config options to avoid measurement collisions:

[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[inputs.cpu]]
  percpu = true
  totalcpu = false
  name_override = "percpu_usage"
  fielddrop = ["cpu_time*"]

Output Configuration

Telegraf also supports specifying multiple output sinks to send data to, configuring each output sink is different, but examples can be found by running telegraf -sample-config.

[[outputs.influxdb]]
  urls = [ "http://localhost:8086" ]
  database = "telegraf"
  precision = "s"
  # Drop all measurements that start with "aerospike"
  namedrop = ["aerospike*"]

[[outputs.influxdb]]
  urls = [ "http://localhost:8086" ]
  database = "telegraf-aerospike-data"
  precision = "s"
  # Only accept aerospike data:
  namepass = ["aerospike*"]

[[outputs.influxdb]]
  urls = [ "http://localhost:8086" ]
  database = "telegraf-cpu0-data"
  precision = "s"
  # Only store measurements where the tag "cpu" matches the value "cpu0"
  [outputs.influxdb.tagpass]
    cpu = ["cpu0"]