telegraf/docs/CONFIGURATION.md

365 lines
12 KiB
Markdown
Raw Normal View History

2015-12-11 20:07:32 +00:00
# Telegraf Configuration
You can see the latest config file with all available plugins here:
[telegraf.conf](https://github.com/influxdata/telegraf/blob/master/etc/telegraf.conf)
2016-01-07 22:21:10 +00:00
## Generating a Configuration File
A default Telegraf config file can be auto-generated by telegraf:
```
telegraf config > telegraf.conf
```
2016-01-07 20:39:43 +00:00
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)
## Configuration file locations
The location of the configuration file can be set via the `--config` command
line flag. Telegraf will also pick up all files matching the pattern `*.conf` if
the `-config-directory` command line flag is used.
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
2016-01-07 22:21:10 +00:00
Telegraf has a few options you can configure under the `[agent]` section of the
2016-01-07 22:21:10 +00:00
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, 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, such as logparser and statsd. Valid values are
"ns", "us" (or "µs"), "ms", "s".
* **logfile**: Specify the log file name. The empty string means to log to stdout.
* **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.
## Output Configuration
There are no generic configuration options available for all outputs.
## 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.
## 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.
#### Measurement Filtering
2015-12-11 20:07:32 +00:00
Filters can be configured per input, output, processor, or aggregator,
see below for examples.
2015-12-11 20:07:32 +00:00
2016-02-20 05:35:12 +00:00
* **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.
2016-02-20 05:35:12 +00:00
* **fielddrop**: The inverse of pass, if a field name matches, it is not emitted.
fielddrop is not available for outputs.
2015-12-11 20:07:32 +00:00
* **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
2015-12-11 20:07:32 +00:00
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** `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 Examples
2015-12-11 20:07:32 +00:00
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_`.
```toml
[global_tags]
2015-12-11 20:07:32 +00:00
dc = "denver-1"
[agent]
interval = "10s"
# OUTPUTS
[[outputs.influxdb]]
url = "http://192.168.59.103:8086" # required.
database = "telegraf" # required.
precision = "s"
2016-01-07 22:21:10 +00:00
# INPUTS
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = true
totalcpu = false
# filter all fields beginning with 'time_'
2016-03-09 14:46:37 +00:00
fielddrop = ["time_*"]
2015-12-11 20:07:32 +00:00
```
#### Input Config: tagpass and tagdrop
2015-12-11 20:07:32 +00:00
**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.
2015-12-11 20:07:32 +00:00
```toml
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = true
totalcpu = false
2016-03-09 14:46:37 +00:00
fielddrop = ["cpu_time"]
2015-12-11 20:07:32 +00:00
# Don't collect CPU data for cpu6 & cpu7
2016-01-07 20:39:43 +00:00
[inputs.cpu.tagdrop]
2015-12-11 20:07:32 +00:00
cpu = [ "cpu6", "cpu7" ]
2016-01-07 20:39:43 +00:00
[[inputs.disk]]
[inputs.disk.tagpass]
2015-12-11 20:07:32 +00:00
# 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*" ]
```
2016-02-20 05:35:12 +00:00
#### Input Config: fieldpass and fielddrop
2015-12-11 20:07:32 +00:00
```toml
# Drop all metrics for guest & steal CPU usage
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = false
totalcpu = true
2016-02-20 05:35:12 +00:00
fielddrop = ["usage_guest", "usage_steal"]
2015-12-11 20:07:32 +00:00
# Only store inode related metrics for disks
2016-01-07 20:39:43 +00:00
[[inputs.disk]]
2016-02-20 05:35:12 +00:00
fieldpass = ["inodes*"]
```
#### Input Config: namepass and namedrop
```toml
# Drop all metrics about containers for kubelet
[[inputs.prometheus]]
urls = ["http://kube-node-1:4194/metrics"]
namedrop = ["container_*"]
2016-02-20 05:35:12 +00:00
# Only store rest client related metrics for kubelet
[[inputs.prometheus]]
urls = ["http://kube-node-1:4194/metrics"]
namepass = ["rest_client_*"]
2015-12-11 20:07:32 +00:00
```
#### Input Config: taginclude and tagexclude
```toml
# 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
2015-12-11 20:07:32 +00:00
This plugin will emit measurements with the name `cpu_total`
```toml
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
name_suffix = "_total"
percpu = false
totalcpu = true
```
This will emit measurements with the name `foobar`
```toml
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
name_override = "foobar"
percpu = false
totalcpu = true
```
#### Input config: tags
2015-12-11 20:07:32 +00:00
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.
2015-12-11 20:07:32 +00:00
```toml
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = false
totalcpu = true
2016-01-07 20:39:43 +00:00
[inputs.cpu.tags]
2015-12-11 20:07:32 +00:00
tag1 = "foo"
tag2 = "bar"
```
#### Multiple inputs of the same type
2015-12-11 20:07:32 +00:00
2016-01-07 22:21:10 +00:00
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:
2015-12-11 20:07:32 +00:00
```toml
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = false
totalcpu = true
2016-01-07 20:39:43 +00:00
[[inputs.cpu]]
2015-12-11 20:07:32 +00:00
percpu = true
totalcpu = false
2016-01-07 22:21:10 +00:00
name_override = "percpu_usage"
2016-03-09 14:46:37 +00:00
fielddrop = ["cpu_time*"]
2015-12-11 20:07:32 +00:00
```
#### Output Configuration Examples:
2015-12-11 20:07:32 +00:00
```toml
[[outputs.influxdb]]
urls = [ "http://localhost:8086" ]
database = "telegraf"
precision = "s"
# Drop all measurements that start with "aerospike"
namedrop = ["aerospike*"]
2015-12-11 20:07:32 +00:00
[[outputs.influxdb]]
urls = [ "http://localhost:8086" ]
database = "telegraf-aerospike-data"
precision = "s"
# Only accept aerospike data:
namepass = ["aerospike*"]
2015-12-11 20:07:32 +00:00
[[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"]
```
#### Aggregator Configuration Examples:
This will collect and emit the min/max of the system load1 metric every
30s, dropping the originals.
```toml
[[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.
```toml
[[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"]
```