Fixup some disk usage reporting, make it reflect df

fixes influxdata#513

CONTRIBUTING.md

@@ -1,10 +1,16 @@
 ## Steps for Contributing:
 
-1. [Sign the CLA](https://github.com/influxdata/telegraf/blob/master/CONTRIBUTING.md#sign-the-cla)
-1. Write your input or output plugin (see below for details)
+1. [Sign the CLA](http://influxdb.com/community/cla.html)
+1. Make changes or write plugin (see below for details)
 1. Add your plugin to `plugins/inputs/all/all.go` or `plugins/outputs/all/all.go`
 1. If your plugin requires a new Go package,
 [add it](https://github.com/influxdata/telegraf/blob/master/CONTRIBUTING.md#adding-a-dependency)
+1. Write a README for your plugin, if it's an input plugin, it should be structured
+like the [input example here](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/EXAMPLE_README.md).
+Output plugins READMEs are less structured,
+but any information you can provide on how the data will look is appreciated.
+See the [OpenTSDB output](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/opentsdb)
+for a good example.
 
 ## Sign the CLA
 

plugins/inputs/EXAMPLE_README.md

@@ -0,0 +1,39 @@
+# Example Input Plugin
+
+The example plugin gathers metrics about example things
+
+### Configuration:
+
+```
+# Description
+[[inputs.example]]
+  # SampleConfig
+```
+
+### Measurements & Fields:
+
+<optional description>
+
+- measurement1
+    - field1 (type, unit)
+    - field2 (float, percent)
+- measurement2
+    - field3 (integer, bytes)
+
+### Tags:
+
+- All measurements have the following tags:
+    - tag1 (optional description)
+    - tag2
+- measurement2 has the following tags:
+    - tag3
+
+### Example Output:
+
+Give an example `-test` output here
+
+```
+$ ./telegraf -config telegraf.conf -input-filter example -test
+measurement1,tag1=foo,tag2=bar field1=1i,field2=2.1 1453831884664956455
+measurement2,tag1=foo,tag2=bar,tag3=baz field3=1i 1453831884664956455
+```

plugins/inputs/system/DISK_README.md

@@ -0,0 +1,45 @@
+# Disk Input Plugin
+
+The disk input plugin gathers metrics about disk usage.
+
+Note that `used_percent` is calculated by doing `used / (used + free)`, _not_
+`used / total`, which is how the unix `df` command does it. See
+https://en.wikipedia.org/wiki/Df_(Unix) for more details.
+
+### Configuration:
+
+```
+# Read metrics about disk usage by mount point
+[[inputs.disk]]
+  # By default, telegraf gather stats for all mountpoints.
+  # Setting mountpoints will restrict the stats to the specified mountpoints.
+  # mount_points = ["/"]
+```
+
+### Measurements & Fields:
+
+- disk
+    - free (integer, bytes)
+    - total (integer, bytes)
+    - used (integer, bytes)
+    - used_percent (float, percent)
+    - inodes_free (integer, files)
+    - inodes_total (integer, files)
+    - inodes_used (integer, files)
+
+### Tags:
+
+- All measurements have the following tags:
+    - fstype (filesystem type)
+    - path (mount point path)
+
+### Example Output:
+
+```
+% ./telegraf -config ~/ws/telegraf.conf -input-filter disk -test
+* Plugin: disk, Collection 1
+> disk,fstype=hfs,path=/ free=398407520256i,inodes_free=97267461i,inodes_total=121847806i,inodes_used=24580345i,total=499088621568i,used=100418957312i,used_percent=20.131039916242397 1453832006274071563
+> disk,fstype=devfs,path=/dev free=0i,inodes_free=0i,inodes_total=628i,inodes_used=628i,total=185856i,used=185856i,used_percent=100 1453832006274137913
+> disk,fstype=autofs,path=/net free=0i,inodes_free=0i,inodes_total=0i,inodes_used=0i,total=0i,used=0i,used_percent=0 1453832006274157077
+> disk,fstype=autofs,path=/home free=0i,inodes_free=0i,inodes_total=0i,inodes_used=0i,total=0i,used=0i,used_percent=0 1453832006274169688
+```

plugins/inputs/system/disk.go

@@ -45,13 +45,20 @@ func (s *DiskStats) Gather(acc inputs.Accumulator) error {
 			"path":   du.Path,
 			"fstype": du.Fstype,
 		}
+		var used_percent float64
+		if du.Used+du.Free > 0 {
+			used_percent = float64(du.Used) /
+				(float64(du.Used) + float64(du.Free)) * 100
+		}
+
 		fields := map[string]interface{}{
 			"total":        du.Total,
 			"free":         du.Free,
-			"used":         du.Total - du.Free,
+			"used":         du.Used,
+			"used_percent": used_percent,
 			"inodes_total": du.InodesTotal,
 			"inodes_free":  du.InodesFree,
-			"inodes_used":  du.InodesTotal - du.InodesFree,
+			"inodes_used":  du.InodesUsed,
 		}
 		acc.AddFields("disk", fields, tags)
 	}

plugins/inputs/system/disk_test.go

@@ -21,16 +21,20 @@ func TestDiskStats(t *testing.T) {
 			Fstype:      "ext4",
 			Total:       128,
 			Free:        23,
+			Used:        100,
 			InodesTotal: 1234,
 			InodesFree:  234,
+			InodesUsed:  1000,
 		},
 		{
 			Path:        "/home",
 			Fstype:      "ext4",
 			Total:       256,
 			Free:        46,
+			Used:        200,
 			InodesTotal: 2468,
 			InodesFree:  468,
+			InodesUsed:  2000,
 		},
 	}
 	duFiltered := []*disk.DiskUsageStat{
@@ -39,8 +43,10 @@ func TestDiskStats(t *testing.T) {
 			Fstype:      "ext4",
 			Total:       128,
 			Free:        23,
+			Used:        100,
 			InodesTotal: 1234,
 			InodesFree:  234,
+			InodesUsed:  1000,
 		},
 	}
 
@@ -52,7 +58,7 @@ func TestDiskStats(t *testing.T) {
 	require.NoError(t, err)
 
 	numDiskPoints := acc.NFields()
-	expectedAllDiskPoints := 12
+	expectedAllDiskPoints := 14
 	assert.Equal(t, expectedAllDiskPoints, numDiskPoints)
 
 	tags1 := map[string]string{
@@ -66,32 +72,34 @@ func TestDiskStats(t *testing.T) {
 
 	fields1 := map[string]interface{}{
 		"total":        uint64(128),
-		"used":         uint64(105),
+		"used":         uint64(100),
 		"free":         uint64(23),
 		"inodes_total": uint64(1234),
 		"inodes_free":  uint64(234),
 		"inodes_used":  uint64(1000),
+		"used_percent": float64(81.30081300813008),
 	}
 	fields2 := map[string]interface{}{
 		"total":        uint64(256),
-		"used":         uint64(210),
+		"used":         uint64(200),
 		"free":         uint64(46),
 		"inodes_total": uint64(2468),
 		"inodes_free":  uint64(468),
 		"inodes_used":  uint64(2000),
+		"used_percent": float64(81.30081300813008),
 	}
 	acc.AssertContainsTaggedFields(t, "disk", fields1, tags1)
 	acc.AssertContainsTaggedFields(t, "disk", fields2, tags2)
 
 	// We expect 6 more DiskPoints to show up with an explicit match on "/"
 	// and /home not matching the /dev in MountPoints
 	err = (&DiskStats{ps: &mps, MountPoints: []string{"/", "/dev"}}).Gather(&acc)
-	assert.Equal(t, expectedAllDiskPoints+6, acc.NFields())
+	assert.Equal(t, expectedAllDiskPoints+7, acc.NFields())
 
 	// We should see all the diskpoints as MountPoints includes both
 	// / and /home
 	err = (&DiskStats{ps: &mps, MountPoints: []string{"/", "/home"}}).Gather(&acc)
-	assert.Equal(t, 2*expectedAllDiskPoints+6, acc.NFields())
+	assert.Equal(t, 2*expectedAllDiskPoints+7, acc.NFields())
 }
 
 // func TestDiskIOStats(t *testing.T) {