diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5e1b406d4114e6ef763e67d653c8e82e7ef0901e..1dad3ab17e2b162e9e2a8f85d3b321e366b592e7 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/plugins/inputs/EXAMPLE_README.md b/plugins/inputs/EXAMPLE_README.md
new file mode 100644
index 0000000000000000000000000000000000000000..16aaac8effd5a9b1e940e85048de9961e2207064
--- /dev/null
+++ b/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
+```
diff --git a/plugins/inputs/system/DISK_README.md b/plugins/inputs/system/DISK_README.md
new file mode 100644
index 0000000000000000000000000000000000000000..c89007b458aa78b399c05a844b0d452d7d44f0b6
--- /dev/null
+++ b/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
+```
diff --git a/plugins/inputs/system/disk.go b/plugins/inputs/system/disk.go
index c6b23492b9078c592ebc456df65f4ec431523adf..5143859d1925b8574bcd241ef7372d8e1b59c2b5 100644
--- a/plugins/inputs/system/disk.go
+++ b/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)
}
diff --git a/plugins/inputs/system/disk_test.go b/plugins/inputs/system/disk_test.go
index ec4182cb395c73d6114ad534221893ddd5b72dc9..8a31957c0d568bdb3dc7c7fef9e1051646a1a2b7 100644
--- a/plugins/inputs/system/disk_test.go
+++ b/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,19 +72,21 @@ 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)
@@ -86,12 +94,12 @@ func TestDiskStats(t *testing.T) {
// 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) {