README updates for readability and ease of use

This commit is contained in:
Cameron Sparr 2015-08-13 13:44:41 -06:00
parent 04963f12a3
commit 4ce61875a4
1 changed files with 59 additions and 60 deletions

119
README.md
View File

@ -35,21 +35,9 @@ brew install telegraf
* Run `telegraf -sample-config > telegraf.toml` to create an initial configuration * Run `telegraf -sample-config > telegraf.toml` to create an initial configuration
* Edit the configuration to match your needs * Edit the configuration to match your needs
* Run `telegraf -config telegraf.toml -test` to output one full measurement sample to STDOUT * Run `telegraf -config telegraf.toml -test` to output one full measurement sample to STDOUT
* Run `telegraf -config telegraf.toml` to gather and send metrics to InfluxDB * Run `telegraf -config telegraf.toml` to gather and send metrics to configured outputs.
* Run `telegraf -config telegraf.toml -filter system:swap` to enable only two plugins described into config file * Run `telegraf -config telegraf.toml -filter system:swap`
to enable only the system & swap plugins defined in the config.
### Telegraf Usage
```telegraf --help```
* -config="": configuration file to load
* -debug=false: show metrics as they're generated to stdout
* -filter="": filter the plugins to enable, separator is :
* -httptest.serve="": if non-empty, httptest.NewServer serves on this address and blocks
* -pidfile="": file to write our pid to
* -sample-config=false: print out full sample configuration
* -test=false: gather metrics, print them out, and exit
* -version=false: display the version
## Telegraf Options ## Telegraf Options
@ -66,6 +54,62 @@ unit parser, ie "10s" for 10 seconds or "5m" for 5 minutes.
* **debug**: Set to true to gather and send metrics to STDOUT as well as * **debug**: Set to true to gather and send metrics to STDOUT as well as
InfluxDB. InfluxDB.
## Plugin Options
There are 5 configuration options that are configurable per plugin:
* **pass**: An array of strings that is used to filter metrics generated by the
current plugin. Each string in the array is tested as a prefix against metric names
and if it matches, the metric is emitted.
* **drop**: The inverse of pass, if a metric name matches, it is not emitted.
* **tagpass**: tag names and arrays of strings that are used to filter metrics by
the current plugin. Each string in the array is tested as an exact match against
the tag name, and if it matches the metric is emitted.
* **tagdrop**: The inverse of tagpass. If a tag matches, the metric is not emitted.
This is tested on metrics that have passed the tagpass test.
* **interval**: How often to gather this metric. Normal plugins use a single
global interval, but if one particular plugin should be run less or more often,
you can configure that here.
### Plugin 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 totalcpu & percpu data.
```
[outputs]
[outputs.influxdb]
url = "http://192.168.59.103:8086" # required.
database = "telegraf" # required.
[tags]
dc = "denver-1"
[agent]
interval = "10s"
# PLUGINS
[cpu]
percpu = true
totalcpu = true
```
Below is how to configure `tagpass` parameters (added in 0.1.5)
```
# Don't collect CPU data for cpu6 & cpu7
[cpu.tagdrop]
cpu = [ "cpu6", "cpu7" ]
[disk]
[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" ]
path = [ "/opt", "/home" ]
```
## Supported Plugins ## Supported Plugins
Telegraf currently has support for collecting metrics from: Telegraf currently has support for collecting metrics from:
@ -87,51 +131,6 @@ Telegraf currently has support for collecting metrics from:
We'll be adding support for many more over the coming months. Read on if you We'll be adding support for many more over the coming months. Read on if you
want to add support for another service or third-party API. want to add support for another service or third-party API.
## Plugin Options
There are 3 configuration options that are configurable per plugin:
* **pass**: An array of strings that is used to filter metrics generated by the
current plugin. Each string in the array is tested as a prefix against metric names
and if it matches, the metric is emitted.
* **drop**: The inverse of pass, if a metric name matches, it is not emitted.
* **tagpass**: tag names and arrays of strings that are used to filter metrics by
the current plugin. Each string in the array is tested as an exact match against
the tag name, and if it matches the metric is emitted.
* **tagdrop**: The inverse of tagpass. If a tag matches, the metric is not emitted.
This is tested on metrics that have passed the tagpass test.
* **interval**: How often to gather this metric. Normal plugins use a single
global interval, but if one particular plugin should be run less or more often,
you can configure that here.
### Plugin Configuration Examples
```
# Read metrics about disk usage by mount point
[disk]
interval = "1m" # Run at a 1 minute interval instead of the default
[disk.tagpass]
# These tag 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" ]
path = [ "/opt", "/home" ]
[postgresql]
[postgresql.tagdrop]
# Don't report stats about the database name 'testdatabase'
db = [ "testdatabase" ]
```
```
[disk]
# Don't report stats about the following filesystem types
[disk.tagdrop]
fstype = [ "nfs", "tmpfs", "ecryptfs" ]
```
## Plugins ## Plugins
This section is for developers that want to create new collection plugins. This section is for developers that want to create new collection plugins.