[WIP] Release 0.3.0

.gitignore

@@ -2,3 +2,5 @@ tivan
 .vagrant
 /telegraf
 .idea
+*~
+*#

CHANGELOG.md

@@ -1,3 +1,41 @@
+## v0.3.0 [unreleased]
+
+### Release Notes
+- Linux packages have been taken out of `opt`, the binary is now in `/usr/bin`
+and configuration files are in `/etc/telegraf`
+- **breaking change** `plugins` have been renamed to `inputs`. This was done because
+`plugins` is too generic, as there are now also "output plugins", and will likely
+be "aggregator plugins" and "filter plugins" in the future. Additionally,
+`inputs/` and `outputs/` directories have been placed in the root-level `plugins/`
+directory.
+- **breaking change** the `io` plugin has been renamed `diskio`
+- **breaking change** plugin measurements aggregated into a single measurement.
+- **breaking change** `jolokia` plugin: must use global tag/drop/pass parameters
+for configuration.
+- **breaking change** `twemproxy` plugin: `prefix` option removed.
+- **breaking change** `procstat` cpu measurements are now prepended with `cpu_time_`
+instead of only `cpu_`
+- **breaking change** some command-line flags have been renamed to separate words.
+`-configdirectory` -> `-config-directory`, `-filter` -> `-input-filter`,
+`-outputfilter` -> `-output-filter`
+- The prometheus plugin schema has not been changed (measurements have not been
+aggregated).
+
+### Packaging change note:
+
+RHEL/CentOS users upgrading from 0.2 to 0.3 will probably have their
+configurations overwritten by the upgrade. There is a backup stored at
+/etc/telegraf/telegraf.conf.$(date +%s).backup.
+
+### Features
+- Plugin measurements aggregated into a single measurement.
+- Added ability to specify per-plugin tags
+- Added ability to specify per-plugin measurement suffix and prefix.
+(`name_prefix` and `name_suffix`)
+- Added ability to override base plugin measurement name. (`name_override`)
+
+### Bugfixes
+
 ## v0.2.5 [unreleased]
 
 ### Features
@@ -38,11 +76,11 @@ functional.
 same type can be specified, like this:
 
 ```
-[[plugins.cpu]]
+[[inputs.cpu]]
   percpu = false
   totalcpu = true
 
-[[plugins.cpu]]
+[[inputs.cpu]]
   percpu = true
   totalcpu = false
   drop = ["cpu_time"]
@@ -69,7 +107,7 @@ same type can be specified, like this:
 lists of servers/URLs. 0.2.2 is being released solely to fix that bug
 
 ### Bugfixes
-- [#377](https://github.com/influxdb/telegraf/pull/377): Fix for duplicate slices in plugins.
+- [#377](https://github.com/influxdb/telegraf/pull/377): Fix for duplicate slices in inputs.
 
 ## v0.2.1 [2015-11-16]
 
@@ -130,7 +168,7 @@ be controlled via the `round_interval` and `flush_jitter` config options.
 - [#241](https://github.com/influxdb/telegraf/pull/241): MQTT Output. Thanks @shirou!
 - Memory plugin: cached and buffered measurements re-added
 - Logging: additional logging for each collection interval, track the number
-of metrics collected and from how many plugins.
+of metrics collected and from how many inputs.
 - [#240](https://github.com/influxdb/telegraf/pull/240): procstat plugin, thanks @ranjib!
 - [#244](https://github.com/influxdb/telegraf/pull/244): netstat plugin, thanks @shirou!
 - [#262](https://github.com/influxdb/telegraf/pull/262): zookeeper plugin, thanks @jrxFive!
@@ -163,7 +201,7 @@ will still be backwards compatible if only `url` is specified.
 - The -test flag will now output two metric collections
 - Support for filtering telegraf outputs on the CLI -- Telegraf will now
 allow filtering of output sinks on the command-line using the `-outputfilter`
-flag, much like how the `-filter` flag works for plugins.
+flag, much like how the `-filter` flag works for inputs.
 - Support for filtering on config-file creation -- Telegraf now supports
 filtering to -sample-config command. You can now run
 `telegraf -sample-config -filter cpu -outputfilter influxdb` to get a config

CONFIGURATION.md

@@ -0,0 +1,199 @@
+# Telegraf Configuration
+
+## Generating a Configuration File
+
+A default Telegraf config file can be generated using the `-sample-config` flag,
+like this: `telegraf -sample-config`
+
+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`
+
+## 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
+
+There are some configuration options that are configurable per input:
+
+* **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.
+* **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.
+
+### Input Filters
+
+There are also filters that can be configured per input:
+
+* **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
+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
+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.
+
+### Input 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 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"
+
+# INPUTS
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  # filter all fields beginning with 'time_'
+  drop = ["time_*"]
+```
+
+### Input Config: tagpass and tagdrop
+
+```toml
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  drop = ["cpu_time"]
+  # Don't collect CPU data for cpu6 & cpu7
+  [inputs.cpu.tagdrop]
+    cpu = [ "cpu6", "cpu7" ]
+
+[[inputs.disk]]
+  [inputs.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" ]
+    # Globs can also be used on the tag values
+    path = [ "/opt", "/home*" ]
+```
+
+### Input Config: pass and drop
+
+```toml
+# Drop all metrics for guest & steal CPU usage
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+  drop = ["usage_guest", "usage_steal"]
+
+# Only store inode related metrics for disks
+[[inputs.disk]]
+  pass = ["inodes*"]
+```
+
+### Input config: prefix, suffix, and override
+
+This plugin will emit measurements with the name `cpu_total`
+
+```toml
+[[inputs.cpu]]
+  name_suffix = "_total"
+  percpu = false
+  totalcpu = true
+```
+
+This will emit measurements with the name `foobar`
+
+```toml
+[[inputs.cpu]]
+  name_override = "foobar"
+  percpu = false
+  totalcpu = true
+```
+
+### Input config: tags
+
+This plugin will emit measurements with two additional tags: `tag1=foo` and
+`tag2=bar`
+
+```toml
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+  [inputs.cpu.tags]
+    tag1 = "foo"
+    tag2 = "bar"
+```
+
+### Multiple inputs of the same type
+
+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:
+
+```toml
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  name_override = "percpu_usage"
+  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`.
+
+Outputs also support the same configurable options as inputs
+(pass, drop, tagpass, tagdrop)
+
+```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"]
+```