Skip to content

Latest commit

 

History

History
445 lines (344 loc) · 14 KB

CONFIGURATION.md

File metadata and controls

445 lines (344 loc) · 14 KB
Raw

Configuration

Telegraf's configuration file is written using TOML.

View the telegraf.conf config file with all available plugins.

Generating a Configuration File

A default config file can be generated by telegraf:

telegraf config > telegraf.conf

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

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

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)

When using the .deb or .rpm packages, you can define environment variables in the /etc/default/telegraf file.

Configuration file locations

The location of the configuration file can be set via the --config command line flag.

When the --config-directory command line flag is used files ending with .conf in the specified directory will also be included in the Telegraf configuration.

On most systems, the default locations are /etc/telegraf/telegraf.conf for the main configuration file and /etc/telegraf/telegraf.d for the directory of configuration files.

Global Tags

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 send metrics to output in batch of at most metric_batch_size metrics.

  • metric_buffer_limit: Telegraf will cache metric_buffer_limit metrics for each output, and will flush this buffer on a successful write. This should be a multiple of metric_batch_size and could not be less than 2 times metric_batch_size.

  • collection_jitter: Collection jitter is used to jitter the collection by a random amount. Each plugin will sleep for a random time within jitter before collecting. This can be used to avoid many 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. Maximum flush_interval will be flush_interval + flush_jitter

  • flush_jitter: Jitter the flush interval by a random amount. This is primarily to avoid large write spikes for users running a large number of telegraf instances. ie, a jitter of 5s and flush_interval 10s means flushes will happen every 10-15s.

  • precision: By default or when set to "0s", precision will be set to the same timestamp order as the collection interval, with the maximum being 1s. Precision will NOT be used for service inputs. It is up to each individual service input to set the timestamp at the appropriate precision. Valid time units are "ns", "us" (or "µs"), "ms", "s".

  • logfile: Specify the log file name. The empty string means to log to stderr.

  • debug: Run telegraf in debug mode.

  • quiet: Run telegraf in quiet mode (error messages only).

  • hostname: Override default hostname, if empty use os.Hostname().

  • omit_hostname: If true, do no set the "host" tag in the telegraf agent.

Input Configuration

The following config parameters are available for all inputs:

  • 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.
  • 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.

The metric filtering parameters can be used to limit what metrics are emitted from the input plugin.

Output Configuration

  • flush_interval: The maximum time between flushes. Use this setting to override the agent flush_interval on a per plugin basis.
  • metric_batch_size: The maximum number of metrics to send at once. Use this setting to override the agent metric_batch_size on a per plugin basis.
  • metric_buffer_limit: The maximum number of unsent metrics to buffer. Use this setting to override the agent metric_buffer_limit on a per plugin basis.

The metric filtering parameters can be used to limit what metrics are emitted from the output plugin.

Aggregator Configuration

The following config parameters are available for all aggregators:

  • period: The period on which to flush & clear each aggregator. All metrics that are sent with timestamps outside of this period will be ignored by the aggregator.
  • delay: The delay before each aggregator is flushed. This is to control how long for aggregators to wait before receiving metrics from input plugins, in the case that aggregators are flushing and inputs are gathering on the same interval.
  • drop_original: If true, the original metric will be dropped by the aggregator and will not get sent to the output plugins.
  • 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.

The metric filtering parameters can be used to limit what metrics are handled by the aggregator. Excluded metrics are passed downstream to the next aggregator.

Processor Configuration

The following config parameters are available for all processors:

  • order: This is the order in which the processor(s) get executed. If this is not specified then processor execution order will be random.

The metric filtering parameters can be used to limit what metrics are handled by the processor. Excluded metrics are passed downstream to the next processor.

Metric Filtering

Metric filtering can be configured per plugin on any input, output, processor, and aggregator plugin. Filters fall under two categories: Selectors and Modifiers.

Selectors

Selector filters include or exclude entire metrics. When a metric is excluded from a Input or an Output plugin, the metric is dropped. If a metric is excluded from a Processor or Aggregator plugin, it is skips the plugin and is sent onwards to the next stage of processing.

  • namepass: An array of glob pattern strings. Only metrics whose measurement name matches a pattern in this list are emitted.

  • namedrop: The inverse of namepass. If a match is found the metric is discarded. This is tested on metrics after they have passed the namepass test.

  • tagpass: A table mapping tag keys to arrays of glob pattern strings. Only metrics that contain a tag key in the table and a tag value matching one of its patterns is emitted.

  • tagdrop: The inverse of tagpass. If a match is found the metric is discarded. This is tested on metrics after they have passed the tagpass test.

Modifiers

Modifier filters remove tags and fields from a metric. If all fields are removed the metric is removed.

  • fieldpass: An array of glob pattern strings. Only fields whose field key matches a pattern in this list are emitted.

  • fielddrop: The inverse of fieldpass. Fields with a field key matching one of the patterns will be discarded from the metric. This is tested on metrics after they have passed the fieldpass test.

  • taginclude: An array of glob pattern strings. Only tags with a tag key matching one of the patterns are emitted. In contrast to tagpass, which will pass an entire metric based on its tag, taginclude removes all non matching tags from the metric. Any tag can be filtered including global tags and the agent host tag.

  • tagexclude: The inverse of taginclude. Tags with a tag key matching one of the patterns will be discarded from the metric. Any tag can be filtered including global tags and the agent host tag.

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.

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

Input Config: tagpass and tagdrop

NOTE 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*" ]
    
    
[[inputs.win_perf_counters]]
  [[inputs.win_perf_counters.object]]
    ObjectName = "Network Interface"
    Instances = ["*"]
    Counters = [
      "Bytes Received/sec",
      "Bytes Sent/sec"
    ]
    Measurement = "win_net"
  # Don't send metrics where the Windows interface name (instance) begins with isatap or Local
  [inputs.win_perf_counters.tagdrop]
    instance = ["isatap*", "Local*"]

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 Examples:

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

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

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

Aggregator Configuration Examples:

This will collect and emit the min/max of the system load1 metric every 30s, dropping the originals.

[[inputs.system]]
  fieldpass = ["load1"] # collects system load1 metric.

[[aggregators.minmax]]
  period = "30s"        # send & clear the aggregate every 30s.
  drop_original = true  # drop the original metrics.

[[outputs.file]]
  files = ["stdout"]

This will collect and emit the min/max of the swap metrics every 30s, dropping the originals. The aggregator will not be applied to the system load metrics due to the namepass parameter.

[[inputs.swap]]

[[inputs.system]]
  fieldpass = ["load1"] # collects system load1 metric.

[[aggregators.minmax]]
  period = "30s"        # send & clear the aggregate every 30s.
  drop_original = true  # drop the original metrics.
  namepass = ["swap"]   # only "pass" swap metrics through the aggregator.

[[outputs.file]]
  files = ["stdout"]

Processor Configuration Examples:

Print only the metrics with cpu as the measurement name, all metrics are passed to the output:

[[processors.printer]]
  namepass = "cpu"

[[outputs.file]]
  files = ["/tmp/metrics.out"]