telegraf/CONFIGURATION.md

200 lines
5.4 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,
like this: `telegraf -sample-config`
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, like this:
`telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka`
2016-01-07 22:21:10 +00:00
## Telegraf Agent Configuration
Telegraf has a few options you can configure under the `agent` section of the
config.
* **hostname**: The hostname is passed as a tag. By default this will be
the value returned by `hostname` on the machine running Telegraf.
You can override that value here.
* **interval**: How often to gather metrics. Uses a simple number +
unit parser, e.g. "10s" for 10 seconds or "5m" for 5 minutes.
* **debug**: Set to true to gather and send metrics to STDOUT as well as
InfluxDB.
## Input 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
2016-01-07 22:21:10 +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
* **pass**: 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.
* **drop**: The inverse of pass, if a field name matches, it is not emitted.
* **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
2016-01-07 22:21:10 +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
[tags]
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_'
drop = ["time_*"]
```
2016-01-07 22:21:10 +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
drop = ["cpu_time"]
# 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-01-07 22:21:10 +00:00
### Input Config: pass and drop
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
drop = ["usage_guest", "usage_steal"]
# Only store inode related metrics for disks
2016-01-07 20:39:43 +00:00
[[inputs.disk]]
2015-12-11 20:07:32 +00:00
pass = ["inodes*"]
```
2016-01-07 22:21:10 +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
```
2016-01-07 22:21:10 +00:00
### 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"
```
2016-01-07 22:21:10 +00:00
### 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"
2015-12-11 20:07:32 +00:00
drop = ["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`.
2016-01-07 22:21:10 +00:00
Outputs also support the same configurable options as inputs
(pass, drop, 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"
drop = ["aerospike*"]
[[outputs.influxdb]]
urls = [ "http://localhost:8086" ]
database = "telegraf-aerospike-data"
precision = "s"
# Only accept aerospike data:
pass = ["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"]
```