Fix SNMP unit tests on OSX, improve tag config doc

closes #592

CONFIGURATION.md

@@ -2,27 +2,46 @@
 
 ## Generating a Configuration File
 
-A default Telegraf config file can be generated using the `-sample-config` flag,
-like this: `telegraf -sample-config`
+A default Telegraf config file can be generated using the -sample-config flag:
+`telegraf -sample-config > telegraf.conf`
 
 To generate a file with specific inputs and outputs, you can use the
-`-input-filter` and `-output-filter` flags, like this:
+-input-filter and -output-filter flags:
 `telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka`
 
-## Telegraf Agent Configuration
+## `[tags]` Configuration
+
+Global tags can be specific in the `[tags]` section of the config file in
+key="value" format. All metrics being gathered on this host will be tagged
+with the tags specified here.
+
+## `[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
+* **interval**: Default data collection interval for all inputs
+* **round_interval**: Rounds collection interval to 'interval'
+ie, if interval="10s" then always collect on :00, :10, :20, etc.
+* **metric_buffer_limit**: Telegraf will cache metric_buffer_limit metrics
+for each output, and will flush this buffer on a successful write.
+* **collection_jitter**: Collection jitter is used to jitter
+the collection by a random amount.
+Each plugin will sleep for a random time within jitter before collecting.
+This can be used to avoid many plugins querying things like sysfs at the
+same time, which can have a measurable effect on the system.
+* **flush_interval**: Default data flushing interval for all outputs.
+You should not set this below
+interval. Maximum flush_interval will be flush_interval + flush_jitter
+* **flush_jitter**: Jitter the flush interval by a random amount.
+This is primarily to avoid
+large write spikes for users running a large number of telegraf instances.
+ie, a jitter of 5s and flush_interval 10s means flushes will happen every 10-15s.
+* **debug**: Run telegraf in debug mode.
+* **quiet**: Run telegraf in quiet mode.
+* **hostname**: Override default hostname, if empty use os.Hostname().
+
+## `[inputs.xxx]` Configuration
 
 There are some configuration options that are configurable per input:
 
@@ -35,7 +54,7 @@ There are some configuration options that are configurable per input:
 global interval, but if one particular input should be run less or more often,
 you can configure that here.
 
-### Input Filters
+#### Input Filters
 
 There are also filters that can be configured per input:
 
@@ -49,7 +68,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.
 
-### Input 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
@@ -77,7 +96,7 @@ fields which begin with `time_`.
   drop = ["time_*"]
 ```
 
-### Input Config: tagpass and tagdrop
+#### Input Config: tagpass and tagdrop
 
 ```toml
 [[inputs.cpu]]
@@ -98,7 +117,7 @@ fields which begin with `time_`.
     path = [ "/opt", "/home*" ]
 ```
 
-### Input Config: pass and drop
+#### Input Config: pass and drop
 
 ```toml
 # Drop all metrics for guest & steal CPU usage
@@ -112,7 +131,7 @@ fields which begin with `time_`.
   pass = ["inodes*"]
 ```
 
-### Input config: prefix, suffix, and override
+#### Input config: prefix, suffix, and override
 
 This plugin will emit measurements with the name `cpu_total`
 
@@ -132,7 +151,7 @@ This will emit measurements with the name `foobar`
   totalcpu = true
 ```
 
-### Input config: tags
+#### Input config: tags
 
 This plugin will emit measurements with two additional tags: `tag1=foo` and
 `tag2=bar`
@@ -146,7 +165,7 @@ This plugin will emit measurements with two additional tags: `tag1=foo` and
     tag2 = "bar"
 ```
 
-### Multiple inputs of the same type
+#### 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
@@ -165,7 +184,7 @@ to avoid measurement collisions:
   drop = ["cpu_time*"]
 ```
 
-## Output Configuration
+## `[outputs.xxx]` Configuration
 
 Telegraf also supports specifying multiple output sinks to send data to,
 configuring each output sink is different, but examples can be

etc/telegraf.conf

 # Telegraf configuration
 
 # Telegraf is entirely plugin driven. All metrics are gathered from the
-# declared inputs.
+# declared inputs, and sent to the declared outputs.
 
-# Even if a plugin has no configuration, it must be declared in here
-# to be active. Declaring a plugin means just specifying the name
-# as a section with no variables. To deactivate a plugin, comment
-# out the name and any variables.
+# Plugins must be declared in here to be active.
+# To deactivate a plugin, comment out the name and any variables.
 
-# Use 'telegraf -config telegraf.toml -test' to see what metrics a config
+# Use 'telegraf -config telegraf.conf -test' to see what metrics a config
 # file would generate.
 
-# One rule that plugins conform to is wherever a connection string
-# can be passed, the values '' and 'localhost' are treated specially.
-# They indicate to the plugin to use their own builtin configuration to
-# connect to the local system.
-
-# NOTE: The configuration has a few required parameters. They are marked
-# with 'required'. Be sure to edit those to make this configuration work.
-
-# Tags can also be specified via a normal map, but only one form at a time:
+# Global tags can be specified here in key="value" format.
 [tags]
-  # dc = "us-east-1"
+  # dc = "us-east-1" # will tag all metrics with dc=us-east-1
+  # rack = "1a"
 
 # Configuration for telegraf agent
 [agent]
@@ -97,9 +88,9 @@
   # By default, telegraf will gather stats for all devices including
   # disk partitions.
   # Setting devices will restrict the stats to the specified devices.
-  # Devices=["sda","sdb"]
+  # devices = ["sda", "sdb"]
   # Uncomment the following line if you do not need disk serial numbers.
-  # SkipSerialNumber = true
+  # skip_serial_number = true
 
 # Read metrics about memory usage
 [[inputs.mem]]

internal/config/config.go

@@ -136,9 +136,10 @@ var header = `# Telegraf configuration
 # Use 'telegraf -config telegraf.conf -test' to see what metrics a config
 # file would generate.
 
-# Tags can also be specified via a normal map, but only one form at a time:
+# Global tags can be specified here in key="value" format.
 [tags]
-  # dc = "us-east-1"
+  # dc = "us-east-1" # will tag all metrics with dc=us-east-1
+  # rack = "1a"
 
 # Configuration for telegraf agent
 [agent]

plugins/inputs/snmp/snmp_test.go

@@ -55,7 +55,7 @@ func TestSNMPErrorBulk(t *testing.T) {
 		Oid:  ".1.3.6.1.2.1.2.2.1.16",
 	}
 	h := Host{
-		Address: "127.0.0.1",
+		Address: testutil.GetLocalHost(),
 		Collect: []string{"oid1"},
 	}
 	s := Snmp{
@@ -75,7 +75,7 @@ func TestSNMPGet1(t *testing.T) {
 		Oid:  ".1.3.6.1.2.1.2.2.1.16.1",
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -98,7 +98,7 @@ func TestSNMPGet1(t *testing.T) {
 		},
 		map[string]string{
 			"unit": "octets",
-			"host": "127.0.0.1",
+			"host": testutil.GetLocalHost(),
 		},
 	)
 }
@@ -109,7 +109,7 @@ func TestSNMPGet2(t *testing.T) {
 		Oid:  "ifNumber",
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -133,7 +133,7 @@ func TestSNMPGet2(t *testing.T) {
 		},
 		map[string]string{
 			"instance": "0",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
@@ -146,7 +146,7 @@ func TestSNMPGet3(t *testing.T) {
 		Instance: "1",
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -171,7 +171,7 @@ func TestSNMPGet3(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "1",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
@@ -184,7 +184,7 @@ func TestSNMPEasyGet4(t *testing.T) {
 		Instance: "1",
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -210,7 +210,7 @@ func TestSNMPEasyGet4(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "1",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -221,7 +221,7 @@ func TestSNMPEasyGet4(t *testing.T) {
 		},
 		map[string]string{
 			"instance": "0",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
@@ -234,7 +234,7 @@ func TestSNMPEasyGet5(t *testing.T) {
 		Instance: "1",
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -260,7 +260,7 @@ func TestSNMPEasyGet5(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "1",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -271,14 +271,14 @@ func TestSNMPEasyGet5(t *testing.T) {
 		},
 		map[string]string{
 			"instance": "0",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
 
 func TestSNMPEasyGet6(t *testing.T) {
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -301,7 +301,7 @@ func TestSNMPEasyGet6(t *testing.T) {
 		},
 		map[string]string{
 			"instance": "0",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
@@ -314,7 +314,7 @@ func TestSNMPBulk1(t *testing.T) {
 		MaxRepetition: 2,
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -339,7 +339,7 @@ func TestSNMPBulk1(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "1",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -351,7 +351,7 @@ func TestSNMPBulk1(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "2",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -363,7 +363,7 @@ func TestSNMPBulk1(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "3",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -375,7 +375,7 @@ func TestSNMPBulk1(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "36",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }
@@ -392,7 +392,7 @@ func dTestSNMPBulk2(t *testing.T) {
 		MaxRepetition: 2,
 	}
 	h := Host{
-		Address:   "127.0.0.1:31161",
+		Address:   testutil.GetLocalHost() + ":31161",
 		Community: "telegraf",
 		Version:   2,
 		Timeout:   2.0,
@@ -417,7 +417,7 @@ func dTestSNMPBulk2(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "1",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -429,7 +429,7 @@ func dTestSNMPBulk2(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "2",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -441,7 +441,7 @@ func dTestSNMPBulk2(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "3",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 
@@ -453,7 +453,7 @@ func dTestSNMPBulk2(t *testing.T) {
 		map[string]string{
 			"unit":     "octets",
 			"instance": "36",
-			"host":     "127.0.0.1",
+			"host":     testutil.GetLocalHost(),
 		},
 	)
 }

plugins/inputs/system/disk.go

@@ -80,8 +80,8 @@ func (_ *DiskIOStats) Description() string {
 var diskIoSampleConfig = `
   # By default, telegraf will gather stats for all devices including
   # disk partitions.
-  # Setting devices will restrict the stats to the specified devcies.
-  # devices = ["sda","sdb"]
+  # Setting devices will restrict the stats to the specified devices.
+  # devices = ["sda", "sdb"]
   # Uncomment the following line if you do not need disk serial numbers.
   # skip_serial_number = true
 `