From 0270ace3d443463709fbae6cd35117fecea68dcd Mon Sep 17 00:00:00 2001
From: Cameron Sparr <cameronsparr@gmail.com>
Date: Thu, 17 Sep 2015 17:24:01 -0700
Subject: [PATCH] Add a CPU collection plugin README

---
 README.md                    |  6 +--
 plugins/system/CPU_README.md | 77 ++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 plugins/system/CPU_README.md

diff --git a/README.md b/README.md
index fb833c85e..1ccd7f9a7 100644
--- a/README.md
+++ b/README.md
@@ -13,9 +13,6 @@ plugins that Telegraf supports. See the
 [contributing guide](CONTRIBUTING.md) for instructions on
 writing new plugins.
 
-NOTE: Telegraf 0.1.9 will change the name of some cpu usage metrics, see
-[CHANGELOG](CHANGELOG.md) for more details.
-
 ## Installation:
 
 Due to a breaking change to the InfluxDB integer line-protocol, there
@@ -24,6 +21,9 @@ are some InfluxDB compatibility requirements:
 * InfluxDB 0.9.3+ requires Telegraf 0.1.5+
 * InfluxDB 0.9.2 and prior requires Telegraf 0.1.4
 
+NOTE: Telegraf 0.1.9 will change the name of some cpu usage metrics, see
+[CHANGELOG](CHANGELOG.md) for more details.
+
 ### Linux deb and rpm packages:
 
 Latest:
diff --git a/plugins/system/CPU_README.md b/plugins/system/CPU_README.md
new file mode 100644
index 000000000..fe547c564
--- /dev/null
+++ b/plugins/system/CPU_README.md
@@ -0,0 +1,77 @@
+# Telegraf plugin: CPU
+
+The CPU plugin collects standard CPU metrics as defined in `man proc`. All
+architectures do not support all of these metrics.
+
+```
+cpu  3357 0 4313 1362393
+    The amount of time, measured in units of USER_HZ (1/100ths of a second on
+    most architectures, use sysconf(_SC_CLK_TCK) to obtain the right value),
+    that the system spent in various states:
+
+    user   (1) Time spent in user mode.
+
+    nice   (2) Time spent in user mode with low priority (nice).
+
+    system (3) Time spent in system mode.
+
+    idle   (4) Time spent in the idle task.  This value should be USER_HZ times
+    the second entry in the /proc/uptime pseudo-file.
+
+    iowait (since Linux 2.5.41)
+           (5) Time waiting for I/O to complete.
+
+    irq (since Linux 2.6.0-test4)
+           (6) Time servicing interrupts.
+
+    softirq (since Linux 2.6.0-test4)
+           (7) Time servicing softirqs.
+
+    steal (since Linux 2.6.11)
+           (8) Stolen time, which is the time spent in other operating systems
+           when running in a virtualized environment
+
+    guest (since Linux 2.6.24)
+           (9) Time spent running a virtual CPU for guest operating systems
+           under the control of the Linux kernel.
+
+    guest_nice (since Linux 2.6.33)
+           (10) Time spent running a niced guest (virtual CPU for guest operating systems under the control of the Linux kernel).
+```
+
+# Measurements:
+### CPU Time measurements:
+
+Meta:
+- units: CPU Time
+- tags: `cpu=<cpuN> or <cpu-total>`
+
+Measurement names:
+- cpu_user
+- cpu_system
+- cpu_idle
+- cpu_nice
+- cpu_iowait
+- cpu_irq
+- cpu_softirq
+- cpu_steal
+- cpu_guest
+- cpu_guest_nice
+
+### CPU Usage Percent Measurements:
+
+Meta:
+- units: percent (out of 100)
+- tags: `cpu=<cpuN> or <cpu-total>`
+
+Measurement names:
+- cpu_usage_user
+- cpu_usage_system
+- cpu_usage_idle
+- cpu_usage_nice
+- cpu_usage_iowait
+- cpu_usage_irq
+- cpu_usage_softirq
+- cpu_usage_steal
+- cpu_usage_guest
+- cpu_usage_guest_nice