Update new memory unit tests, documentation

CHANGELOG.md

@@ -7,9 +7,10 @@ will still be backwards compatible if only `url` is specified.
 - **Breaking Change**: The CPU collection plugin has been refactored to fix some
 bugs and outdated dependency issues. At the same time, I also decided to fix
 a naming consistency issue, so cpu_percentageIdle will become cpu_usage_idle.
-Also, all CPU time measurements now have it indicated in their name, so cp_idle
-will become cpu_time_idle, additionally, these cpu_time measurements are going
-to be dropped in the default config with a plugin drop parameter.
+Also, all CPU time measurements now have it indicated in their name, so cpu_idle will become cpu_time_idle. Additionally, cpu_time measurements are going to be dropped in the default config.
+- **Breaking Change**: The memory plugin has been refactored and some measurements
+have been renamed for consistency. Some measurements have also been removed from being outputted. They are still being collected by gopsutil, and could easily be
+re-added in a "verbose" mode if there is demand for it.
 
 ### Features
 - [#143](https://github.com/influxdb/telegraf/issues/143): InfluxDB clustering support

plugins/system/CPU_README.md

@@ -1,5 +1,11 @@
 # Telegraf plugin: CPU
 
+#### Plugin arguments:
+- **totalcpu** boolean: If true, include `cpu-total` data
+- **percpu** boolean: If true, include data on a per-cpu basis `cpu0, cpu1, etc.`
+
+#### Description
+
 The CPU plugin collects standard CPU metrics as defined in `man proc`. All
 architectures do not support all of these metrics.
 

plugins/system/MEM_README.md

@@ -0,0 +1,44 @@
+## Telegraf Plugin: MEM
+
+#### Description
+
+The mem plugin collects memory metrics, defined as follows. For a more complete
+explanation of the difference between `used` and `actual_used` RAM, see
+[Linux ate my ram](http://www.linuxatemyram.com/).
+
+- **total**: total physical memory available
+- **actual_free**: the actual amount of available memory that can be given instantly
+to processes that request more memory in bytes; this is calculated by summing
+different memory values depending on the platform (e.g. free + buffers + cached on Linux)
+and it is supposed to be used to monitor actual memory usage in a cross platform fashion.
+- **actual_used**: inverse of actual_free, see above
+- **actual_used_percent**: the percentage usage calculated as (total - actual_used) / total * 100
+- **used**: memory used, calculated differently depending on the platform and
+designed for informational purposes only.
+- **free**: memory not being used at all (zeroed) that is readily available; note
+that this doesn't reflect the actual memory available (use 'available' instead).
+- **used_percent**: the percentage usage calculated as (total - used) / total * 100
+
+## Measurements:
+#### Raw Memory measurements:
+
+Meta:
+- units: bytes
+- tags: `nil`
+
+Measurement names:
+- mem_total
+- mem_actual_free
+- mem_actual_used
+- mem_used
+- mem_free
+
+#### Derived usage percentages:
+
+Meta:
+- units: percent (out of 100)
+- tags: `nil`
+
+Measurement names:
+- mem_used_percent
+- mem_actual_used_percent

plugins/system/memory.go

@@ -29,8 +29,10 @@ func (s *MemStats) Gather(acc plugins.Accumulator) error {
 	acc.Add("actual_used", vm.Total-vm.Available, vmtags)
 	acc.Add("used", vm.Used, vmtags)
 	acc.Add("free", vm.Free, vmtags)
-	acc.Add("used_percent", 100*vm.Used/vm.Total, vmtags)
-	acc.Add("actual_used_percent", 100*(vm.Total-vm.Available)/vm.Total, vmtags)
+	acc.Add("used_percent", 100*float64(vm.Used)/float64(vm.Total), vmtags)
+	acc.Add("actual_used_percent",
+		100*float64(vm.Total-vm.Available)/float64(vm.Total),
+		vmtags)
 
 	return nil
 }

plugins/system/system_test.go

@@ -91,17 +91,16 @@ func TestSystemStats_GenerateStats(t *testing.T) {
 	mps.On("NetIO").Return([]net.NetIOCountersStat{netio}, nil)
 
 	vms := &mem.VirtualMemoryStat{
-		Total:       12400,
-		Available:   7600,
-		Used:        5000,
-		UsedPercent: 47.1,
-		Free:        1235,
-		Active:      8134,
-		Inactive:    1124,
-		Buffers:     771,
-		Cached:      4312,
-		Wired:       134,
-		Shared:      2142,
+		Total:     12400,
+		Available: 7600,
+		Used:      5000,
+		Free:      1235,
+		// Active:      8134,
+		// Inactive:    1124,
+		// Buffers:     771,
+		// Cached:      4312,
+		// Wired:       134,
+		// Shared:      2142,
 	}
 
 	mps.On("VMStat").Return(vms, nil)
@@ -231,16 +230,16 @@ func TestSystemStats_GenerateStats(t *testing.T) {
 	vmtags := map[string]string(nil)
 
 	assert.True(t, acc.CheckTaggedValue("total", uint64(12400), vmtags))
-	assert.True(t, acc.CheckTaggedValue("available", uint64(7600), vmtags))
+	assert.True(t, acc.CheckTaggedValue("actual_free", uint64(7600), vmtags))
+	assert.True(t, acc.CheckTaggedValue("actual_used", uint64(12400-7600), vmtags))
 	assert.True(t, acc.CheckTaggedValue("used", uint64(5000), vmtags))
-	assert.True(t, acc.CheckTaggedValue("used_perc", float64(47.1), vmtags))
+	assert.True(t, acc.CheckTaggedValue("actual_used_percent",
+		float64(12400-7600)/float64(12400)*100,
+		vmtags))
+	assert.True(t, acc.CheckTaggedValue("used_percent",
+		float64(5000)/float64(12400)*100,
+		vmtags))
 	assert.True(t, acc.CheckTaggedValue("free", uint64(1235), vmtags))
-	assert.True(t, acc.CheckTaggedValue("active", uint64(8134), vmtags))
-	assert.True(t, acc.CheckTaggedValue("inactive", uint64(1124), vmtags))
-	assert.True(t, acc.CheckTaggedValue("buffers", uint64(771), vmtags))
-	assert.True(t, acc.CheckTaggedValue("cached", uint64(4312), vmtags))
-	assert.True(t, acc.CheckTaggedValue("wired", uint64(134), vmtags))
-	assert.True(t, acc.CheckTaggedValue("shared", uint64(2142), vmtags))
 
 	acc.Points = nil
 
@@ -251,7 +250,7 @@ func TestSystemStats_GenerateStats(t *testing.T) {
 
 	assert.NoError(t, acc.ValidateTaggedValue("total", uint64(8123), swaptags))
 	assert.NoError(t, acc.ValidateTaggedValue("used", uint64(1232), swaptags))
-	assert.NoError(t, acc.ValidateTaggedValue("used_perc", float64(12.2), swaptags))
+	assert.NoError(t, acc.ValidateTaggedValue("used_percent", float64(12.2), swaptags))
 	assert.NoError(t, acc.ValidateTaggedValue("free", uint64(6412), swaptags))
 	assert.NoError(t, acc.ValidateTaggedValue("in", uint64(7), swaptags))
 	assert.NoError(t, acc.ValidateTaggedValue("out", uint64(830), swaptags))