From 4ce61875a4ca8bba86299c4bf7ea2c41c513abee Mon Sep 17 00:00:00 2001 From: Cameron Sparr Date: Thu, 13 Aug 2015 13:44:41 -0600 Subject: [PATCH] README updates for readability and ease of use --- README.md | 119 +++++++++++++++++++++++++++--------------------------- 1 file changed, 59 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 0ab29f284..2f282b892 100644 --- a/README.md +++ b/README.md @@ -35,22 +35,10 @@ brew install telegraf * Run `telegraf -sample-config > telegraf.toml` to create an initial configuration * 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` to gather and send metrics to InfluxDB -* Run `telegraf -config telegraf.toml -filter system:swap` to enable only two plugins described into config file +* Run `telegraf -config telegraf.toml` to gather and send metrics to configured outputs. +* 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 has a few options you can configure under the `agent` section of the @@ -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 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 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 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 This section is for developers that want to create new collection plugins.