0.3.0: update README and documentation

CHANGELOG.md

@@ -11,8 +11,11 @@ directory.
 - **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** `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).
 

CONFIGURATION.md

@@ -9,7 +9,7 @@ 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`
 
-## Plugin Configuration
+## Input Configuration
 
 There are some configuration options that are configurable per plugin:
 
@@ -22,7 +22,7 @@ There are some configuration options that are configurable per plugin:
 global interval, but if one particular plugin should be run less or more often,
 you can configure that here.
 
-### Plugin Filters
+### Input Filters
 
 There are also filters that can be configured per plugin:
 
@@ -36,7 +36,7 @@ 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.
 
-### Plugin Configuration Examples
+### 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
@@ -57,19 +57,19 @@ fields which begin with `time_`.
   database = "telegraf" # required.
   precision = "s"
 
-# PLUGINS
-[plugins]
+# INPUTS
+[inputs]
 [[inputs.cpu]]
   percpu = true
   totalcpu = false
   # filter all fields beginning with 'time_'
   drop = ["time_*"]
 ```
 
-### Plugin Config: tagpass and tagdrop
+### Input Config: tagpass and tagdrop
 
 ```toml
-[plugins]
+[inputs]
 [[inputs.cpu]]
   percpu = true
   totalcpu = false
@@ -88,7 +88,7 @@ fields which begin with `time_`.
     path = [ "/opt", "/home*" ]
 ```
 
-### Plugin Config: pass and drop
+### Input Config: pass and drop
 
 ```toml
 # Drop all metrics for guest & steal CPU usage
@@ -102,7 +102,7 @@ fields which begin with `time_`.
   pass = ["inodes*"]
 ```
 
-### Plugin config: prefix, suffix, and override
+### Input config: prefix, suffix, and override
 
 This plugin will emit measurements with the name `cpu_total`
 
@@ -122,7 +122,7 @@ This will emit measurements with the name `foobar`
   totalcpu = true
 ```
 
-### Plugin config: tags
+### Input config: tags
 
 This plugin will emit measurements with two additional tags: `tag1=foo` and
 `tag2=bar`
@@ -136,10 +136,12 @@ This plugin will emit measurements with two additional tags: `tag1=foo` and
     tag2 = "bar"
 ```
 
-### Multiple plugins of the same type
+### Multiple inputs of the same type
 
-Additional plugins (or outputs) of the same type can be specified,
-just define more instances in the config file:
+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]]
@@ -149,6 +151,7 @@ just define more instances in the config file:
 [[inputs.cpu]]
   percpu = true
   totalcpu = false
+  name_override = "percpu_usage"
   drop = ["cpu_time*"]
 ```
 
@@ -158,8 +161,8 @@ 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 plugins
-(pass, drop, tagpass, tagdrop), added in 0.2.4
+Outputs also support the same configurable options as inputs
+(pass, drop, tagpass, tagdrop)
 
 ```toml
 [[outputs.influxdb]]

README.md

@@ -1,23 +1,35 @@
-# Telegraf - A native agent for InfluxDB [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf)
+# Telegraf [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf)
 
 Telegraf is an agent written in Go for collecting metrics from the system it's
-running on, or from other services, and writing them into InfluxDB.
+running on, or from other services, and writing them into InfluxDB or other
+[outputs](https://github.com/influxdata/telegraf#supported-output-plugins).
 
 Design goals are to have a minimal memory footprint with a plugin system so
 that developers in the community can easily add support for collecting metrics
 from well known services (like Hadoop, Postgres, or Redis) and third party
 APIs (like Mailchimp, AWS CloudWatch, or Google Analytics).
 
-We'll eagerly accept pull requests for new plugins and will manage the set of
-plugins that Telegraf supports. See the
-[contributing guide](CONTRIBUTING.md) for instructions on
-writing new inputs.
+New input and output plugins are designed to be easy to contribute,
+we'll eagerly accept pull
+requests and will manage the set of plugins that Telegraf supports.
+See the [contributing guide](CONTRIBUTING.md) for instructions on writing
+new plugins.
 
 ## Installation:
 
+NOTE: Telegraf 0.3.x is **not** backwards-compatible with previous versions of
+telegraf, both in the database layout and the configuration file. 0.2.x will
+continue to be supported, see below for download links.
+
+TODO: link to blog post about 0.3.x changes.
+
 ### Linux deb and rpm packages:
 
 Latest:
+* http://get.influxdb.org/telegraf/telegraf_0.3.0_amd64.deb
+* http://get.influxdb.org/telegraf/telegraf-0.3.0-1.x86_64.rpm
+
+0.2.x:
 * http://get.influxdb.org/telegraf/telegraf_0.2.4_amd64.deb
 * http://get.influxdb.org/telegraf/telegraf-0.2.4-1.x86_64.rpm
 
@@ -33,6 +45,11 @@ controlled via `systemctl [action] telegraf`
 ### Linux binaries:
 
 Latest:
+* http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.3.0.tar.gz
+* http://get.influxdb.org/telegraf/telegraf_linux_386_0.3.0.tar.gz
+* http://get.influxdb.org/telegraf/telegraf_linux_arm_0.3.0.tar.gz
+
+0.2.x:
 * http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.2.4.tar.gz
 * http://get.influxdb.org/telegraf/telegraf_linux_386_0.2.4.tar.gz
 * http://get.influxdb.org/telegraf/telegraf_linux_arm_0.2.4.tar.gz
@@ -51,32 +68,6 @@ brew update
 brew install telegraf
 ```
 
-### Version 0.3.0 Beta
-
-Version 0.3.0 will introduce many new breaking changes to Telegraf. For starters,
-plugin measurements will be aggregated into fields. This means that there will no
-longer be a `cpu_usage_idle` measurement, there will be a `cpu` measurement with
-a `usage_idle` field.
-
-There will also be config file changes, meaning that your 0.2.x Telegraf config
-files will no longer work properly. It is recommended that you use the
-`-sample-config` flag to generate a new config file to see what the changes are.
-You can also read the
-[0.3.0 configuration guide](https://github.com/influxdb/telegraf/blob/0.3.0/CONFIGURATION.md)
-to see some of the new features and options available.
-
-You can read more about the justifications for the aggregated measurements
-[here](https://github.com/influxdb/telegraf/issues/152), and a more detailed
-breakdown of the work [here](https://github.com/influxdb/telegraf/pull/437).
-Once we're closer to a full release, there will be a detailed blog post
-explaining all the changes.
-
-* http://get.influxdb.org/telegraf/telegraf_0.3.0-beta2_amd64.deb
-* http://get.influxdb.org/telegraf/telegraf-0.3.0_beta2-1.x86_64.rpm
-* http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.3.0-beta2.tar.gz
-* http://get.influxdb.org/telegraf/telegraf_linux_386_0.3.0-beta2.tar.gz
-* http://get.influxdb.org/telegraf/telegraf_linux_arm_0.3.0-beta2.tar.gz
-
 ### From Source:
 
 Telegraf manages dependencies via [gdm](https://github.com/sparrc/gdm),
@@ -121,7 +112,7 @@ InfluxDB.
 See the [configuration guide](CONFIGURATION.md) for a rundown of the more advanced
 configuration options.
 
-## Supported Plugins
+## Supported Input Plugins
 
 **You can view usage instructions for each plugin by running**
 `telegraf -usage <pluginname>`.
@@ -166,7 +157,7 @@ Telegraf currently has support for collecting metrics from:
     * diskio
     * swap
 
-## Supported Service Plugins
+## Supported Input Service Plugins
 
 Telegraf can collect metrics via the following services:
 
@@ -176,7 +167,7 @@ Telegraf can collect metrics via the following services:
 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.
 
-## Supported Outputs
+## Supported Output Plugins
 
 * influxdb
 * nsq

cmd/telegraf/telegraf.go

@@ -31,43 +31,50 @@ var fOutputFilters = flag.String("output-filter", "",
 var fUsage = flag.String("usage", "",
 	"print usage for a plugin, ie, 'telegraf -usage mysql'")
 
+var fInputFiltersLegacy = flag.String("filter", "",
+	"filter the plugins to enable, separator is :")
+var fOutputFiltersLegacy = flag.String("outputfilter", "",
+	"filter the outputs to enable, separator is :")
+var fConfigDirectoryLegacy = flag.String("configdirectory", "",
+	"directory containing additional *.conf files")
+
 // Telegraf version
 //	-ldflags "-X main.Version=`git describe --always --tags`"
 var Version string
 
-const usage = `Telegraf, The plugin-driven server agent for reporting metrics into InfluxDB
+const usage = `Telegraf, The plugin-driven server agent for collecting and reporting metrics.
 
 Usage:
 
-    telegraf <flags>
+  telegraf <flags>
 
 The flags are:
 
-    -config <file>     configuration file to load
-    -test              gather metrics once, print them to stdout, and exit
-    -sample-config     print out full sample configuration to stdout
-    -config-directory  directory containing additional *.conf files
-    -input-filter      filter the input plugins to enable, separator is :
-    -output-filter     filter the output plugins to enable, separator is :
-    -usage             print usage for a plugin, ie, 'telegraf -usage mysql'
-    -version           print the version to stdout
+  -config <file>     configuration file to load
+  -test              gather metrics once, print them to stdout, and exit
+  -sample-config     print out full sample configuration to stdout
+  -config-directory  directory containing additional *.conf files
+  -input-filter      filter the input plugins to enable, separator is :
+  -output-filter     filter the output plugins to enable, separator is :
+  -usage             print usage for a plugin, ie, 'telegraf -usage mysql'
+  -version           print the version to stdout
 
 Examples:
 
-    # generate a telegraf config file:
-    telegraf -sample-config > telegraf.conf
+  # generate a telegraf config file:
+  telegraf -sample-config > telegraf.conf
 
-    # generate a telegraf config file with only cpu input and influxdb output enabled
-    telegraf -sample-config -input-filter cpu -output-filter influxdb
+  # generate config with only cpu input & influxdb output plugins defined
+  telegraf -sample-config -input-filter cpu -output-filter influxdb
 
-    # run a single telegraf collection, outputting metrics to stdout
-    telegraf -config telegraf.conf -test
+  # run a single telegraf collection, outputing metrics to stdout
+  telegraf -config telegraf.conf -test
 
-    # run telegraf with all plugins defined in config file
-    telegraf -config telegraf.conf
+  # run telegraf with all plugins defined in config file
+  telegraf -config telegraf.conf
 
-    # run telegraf, enabling only the cpu and memory inputs and influxdb output
-    telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb
+  # run telegraf, enabling the cpu & memory input, and influxdb output plugins
+  telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb
 `
 
 func main() {
@@ -79,12 +86,20 @@ func main() {
 	}
 
 	var inputFilters []string
+	if *fInputFiltersLegacy != "" {
+		inputFilter := strings.TrimSpace(*fInputFiltersLegacy)
+		inputFilters = strings.Split(":"+inputFilter+":", ":")
+	}
 	if *fInputFilters != "" {
 		inputFilter := strings.TrimSpace(*fInputFilters)
 		inputFilters = strings.Split(":"+inputFilter+":", ":")
 	}
 
 	var outputFilters []string
+	if *fOutputFiltersLegacy != "" {
+		outputFilter := strings.TrimSpace(*fOutputFiltersLegacy)
+		outputFilters = strings.Split(":"+outputFilter+":", ":")
+	}
 	if *fOutputFilters != "" {
 		outputFilter := strings.TrimSpace(*fOutputFilters)
 		outputFilters = strings.Split(":"+outputFilter+":", ":")
@@ -129,6 +144,13 @@ func main() {
 		return
 	}
 
+	if *fConfigDirectoryLegacy != "" {
+		err = c.LoadDirectory(*fConfigDirectoryLegacy)
+		if err != nil {
+			log.Fatal(err)
+		}
+	}
+
 	if *fConfigDirectory != "" {
 		err = c.LoadDirectory(*fConfigDirectory)
 		if err != nil {