telegraf/docs/CONFIGURATION.md

237 lines
7.2 KiB
Markdown
Raw Normal View History

2015-12-11 20:07:32 +00:00
# Telegraf Configuration
2016-01-07 22:21:10 +00:00
## Generating a Configuration File
A default Telegraf config file can be generated using the -sample-config flag:
`telegraf -sample-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:
2016-01-07 20:39:43 +00:00
`telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka`
## `[global_tags]` Configuration
Global tags can be specific 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
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_buffer_limit**: Telegraf will cache metric_buffer_limit metrics
for each output, and will flush this buffer on a successful write.
* **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.
* **debug**: Run telegraf in debug mode.
* **quiet**: Run telegraf in quiet mode.
* **hostname**: Override default hostname, if empty use os.Hostname().
## `[inputs.xxx]` Configuration
2015-12-11 20:07:32 +00:00
There are some configuration options that are configurable per input:
2015-12-11 20:07:32 +00:00
* **name_override**: Override the base name of the measurement.
(Default is the name of the input).
2015-12-11 20:07:32 +00:00
* **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.
2015-12-11 20:07:32 +00:00
#### Input Filters
2015-12-11 20:07:32 +00:00
There are also filters that can be configured per input:
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
2015-12-11 20:07:32 +00:00
and if it matches, the field is emitted.
2016-02-20 05:35:12 +00:00
* **fielddrop**: The inverse of pass, if a field name matches, it is not emitted.
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.
2015-12-11 20:07:32 +00:00
#### 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
```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_"]
# 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: 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`
```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
```
## `[outputs.xxx]` Configuration
2015-12-11 20:07:32 +00:00
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`.
2016-01-07 22:21:10 +00:00
Outputs also support the same configurable options as inputs
(namepass, namedrop, tagpass, tagdrop)
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"]
```