+ system-metrics: complete source code documentation

fix global context switches metric

13 files changed, 65 insertions, 8 deletions

diff --git a/kamon-system-metrics/src/main/scala/kamon/system/custom/ContextSwitchesMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/custom/ContextSwitchesMetrics.scala
index 4780f44a..7a658a07 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/custom/ContextSwitchesMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/custom/ContextSwitchesMetrics.scala
@@ -30,6 +30,12 @@ import org.hyperic.sigar.Sigar
 import scala.collection.JavaConverters.iterableAsScalaIterableConverter
 import scala.concurrent.duration.FiniteDuration
 
+/**
+ *  Context Switches metrics:
+ *    - perProcessVoluntary: Total number of voluntary context switches related to the current process (one thread explicitly yield the CPU to another).
+ *    - perProcessNonVoluntary: Total number of involuntary context switches related to the current process (the system scheduler suspends and active thread, and switches control to a different thread).
+ *    - global:  Total number of context switches across all CPUs.
+ */
 class ContextSwitchesMetrics(pid: Long, log: LoggingAdapter, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
   val perProcessVoluntary = histogram("context-switches-process-voluntary")
   val perProcessNonVoluntary = histogram("context-switches-process-non-voluntary")
@@ -62,7 +68,7 @@ class ContextSwitchesMetrics(pid: Long, log: LoggingAdapter, instrumentFactory:
 
       try {
         for (line ← Files.readAllLines(Paths.get(filename), StandardCharsets.US_ASCII).asScala.toList) {
-          if (line.startsWith("rcs")) {
+          if (line.startsWith("ctxt")) {
             contextSwitches = line.substring(line.indexOf(" ") + 1).toLong
           }
         }
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/jmx/ClassLoadingMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/jmx/ClassLoadingMetrics.scala
index c64518c3..568f1b71 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/jmx/ClassLoadingMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/jmx/ClassLoadingMetrics.scala
@@ -21,6 +21,10 @@ import java.lang.management.ManagementFactory
 import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.{ Memory, InstrumentFactory }
 
+/**
+ *  Class Loading metrics, as reported by JMX:
+ *    - @see [[http://docs.oracle.com/javase/7/docs/api/java/lang/management/ClassLoadingMXBean.html "ClassLoadingMXBean"]]
+ */
 class ClassLoadingMetrics(instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
   val classLoadingBean = ManagementFactory.getClassLoadingMXBean
 
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/jmx/GarbageCollectionMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/jmx/GarbageCollectionMetrics.scala
index 97aa3142..a9ab4b62 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/jmx/GarbageCollectionMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/jmx/GarbageCollectionMetrics.scala
@@ -22,6 +22,10 @@ import kamon.metric.{ Entity, MetricsExtension, GenericEntityRecorder }
 import kamon.metric.instrument.{ DifferentialValueCollector, Time, InstrumentFactory }
 import scala.collection.JavaConverters._
 
+/**
+ *  Garbage Collection metrics, as reported by JMX:
+ *    - @see [[http://docs.oracle.com/javase/7/docs/api/java/lang/management/GarbageCollectorMXBean.html "GarbageCollectorMXBean"]]
+ */
 class GarbageCollectionMetrics(gc: GarbageCollectorMXBean, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
 
   gauge("garbage-collection-count", DifferentialValueCollector(() ⇒ {
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/jmx/HeapMemoryMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/jmx/HeapMemoryMetrics.scala
index d059727f..cd2e3e8e 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/jmx/HeapMemoryMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/jmx/HeapMemoryMetrics.scala
@@ -21,6 +21,10 @@ import java.lang.management.ManagementFactory
 import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.{ Memory, InstrumentFactory }
 
+/**
+ *  Heap Memory metrics, as reported by JMX:
+ *    - @see [[http://docs.oracle.com/javase/7/docs/api/java/lang/management/MemoryMXBean.html "MemoryMXBean"]]
+ */
 class HeapMemoryMetrics(instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
   val memoryBean = ManagementFactory.getMemoryMXBean
   def nonHeapUsage = memoryBean.getHeapMemoryUsage
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/jmx/NonHeapMemoryMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/jmx/NonHeapMemoryMetrics.scala
index 06c954a3..7425972b 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/jmx/NonHeapMemoryMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/jmx/NonHeapMemoryMetrics.scala
@@ -21,6 +21,10 @@ import java.lang.management.ManagementFactory
 import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.{ Memory, InstrumentFactory }
 
+/**
+ *  Non Heap Memory metrics, as reported by JMX:
+ *    - @see [[http://docs.oracle.com/javase/7/docs/api/java/lang/management/MemoryMXBean.html "MemoryMXBean"]]
+ */
 class NonHeapMemoryMetrics(instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
   val memoryBean = ManagementFactory.getMemoryMXBean
   def nonHeapUsage = memoryBean.getNonHeapMemoryUsage
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/jmx/ThreadsMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/jmx/ThreadsMetrics.scala
index 7dc47a34..b9bf9622 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/jmx/ThreadsMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/jmx/ThreadsMetrics.scala
@@ -21,6 +21,10 @@ import java.lang.management.ManagementFactory
 import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.InstrumentFactory
 
+/**
+ *  Threads metrics, as reported by JMX:
+ *    - @see [[http://docs.oracle.com/javase/7/docs/api/java/lang/management/ThreadMXBean.html "ThreadMXBean"]]
+ */
 class ThreadsMetrics(instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {
   val threadsBean = ManagementFactory.getThreadMXBean
 
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/CpuMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/CpuMetrics.scala
index 62fffc99..0e9a5b53 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/CpuMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/CpuMetrics.scala
@@ -20,6 +20,14 @@ import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.InstrumentFactory
 import org.hyperic.sigar.Sigar
 
+/**
+ *  Cpu usage metrics, as reported by Sigar:
+ *    - user: Total percentage of system cpu user time.
+ *    - system: Total percentage of system cpu kernel time.
+ *    - wait: Total percentage of system cpu io wait time.
+ *    - idle:  Total percentage of system cpu idle time
+ *    - stolen: Total percentage of system cpu involuntary wait time. @see [[https://www.datadoghq.com/2013/08/understanding-aws-stolen-cpu-and-how-it-affects-your-apps/ "Understanding Stolen Cpu"]]
+ */
 class CpuMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
   val user = histogram("cpu-user")
   val system = histogram("cpu-system")
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/DiffRecordingHistogram.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/DiffRecordingHistogram.scala
index d13cbed2..06e3e37d 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/DiffRecordingHistogram.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/DiffRecordingHistogram.scala
@@ -32,11 +32,10 @@ class DiffRecordingHistogram(wrappedHistogram: Histogram) extends Histogram {
   private def processRecording(value: Long, count: Long): Unit = {
     if (_recordedAtLeastOnce) {
       val diff = value - _lastObservedValue.getAndSet(value)
-      val current = if(diff >= 0) diff else 0L
-      
+      val current = if (diff >= 0) diff else 0L
+
       wrappedHistogram.record(current, count)
-    }
-    else {
+    } else {
       _lastObservedValue.set(value)
       _recordedAtLeastOnce = true
     }
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/FileSystemMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/FileSystemMetrics.scala
index 2d516b80..eb327620 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/FileSystemMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/FileSystemMetrics.scala
@@ -21,6 +21,11 @@ import kamon.metric.instrument.{ Memory, InstrumentFactory }
 import org.hyperic.sigar.{ DiskUsage, FileSystem, Sigar }
 import scala.util.Try
 
+/**
+ *  Disk usage metrics, as reported by Sigar:
+ *    - readBytes: Total number of physical disk bytes written.
+ *    - writesBytes:  Total number of physical disk writes.
+ */
 class FileSystemMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
   val reads = DiffRecordingHistogram(histogram("file-system-reads", Memory.Bytes))
   val writes = DiffRecordingHistogram(histogram("file-system-writes", Memory.Bytes))
@@ -29,7 +34,7 @@ class FileSystemMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) exte
 
   def sumOfAllFileSystems(sigar: Sigar, thunk: DiskUsage ⇒ Long): Long = Try {
     fileSystems.map(i ⇒ thunk(sigar.getDiskUsage(i))).fold(0L)(_ + _)
-  } getOrElse (0L)
+  } getOrElse 0L
 
   def update(): Unit = {
     reads.record(sumOfAllFileSystems(sigar, _.getReadBytes))
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/LoadAverageMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/LoadAverageMetrics.scala
index 353cd9a4..8d7bd808 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/LoadAverageMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/LoadAverageMetrics.scala
@@ -20,6 +20,10 @@ import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.InstrumentFactory
 import org.hyperic.sigar.Sigar
 
+/**
+ *  Load Average metrics, as reported by Sigar:
+ *    - The system load averages for the past 1, 5, and 15 minutes.
+ */
 class LoadAverageMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
   val oneMinute = histogram("one-minute")
   val fiveMinutes = histogram("five-minutes")
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/MemoryMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/MemoryMetrics.scala
index b4d627fc..787c9f2f 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/MemoryMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/MemoryMetrics.scala
@@ -24,7 +24,7 @@ import org.hyperic.sigar.Sigar
  *  System memory usage metrics, as reported by Sigar:
  *    - used: Total used system memory.
  *    - free: Total free system memory (e.g. Linux plus cached).
- *    - swap-used: Total used system swap..
+ *    - swap-used: Total used system swap.
  *    - swap-free: Total free system swap.
  */
 class MemoryMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/NetworkMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/NetworkMetrics.scala
index 800f7ec6..30575508 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/NetworkMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/NetworkMetrics.scala
@@ -21,6 +21,15 @@ import kamon.metric.instrument._
 import org.hyperic.sigar.{ NetInterfaceStat, Sigar }
 import scala.util.Try
 
+/**
+ *  Network metrics, as reported by Sigar:
+ *    - rxBytes: Total number of received packets in bytes.
+ *    - txBytes: Total number of transmitted packets in bytes.
+ *    - rxErrors: Total number of packets received with errors. This includes too-long-frames errors, ring-buffer overflow errors, etc.
+ *    - txErrors: Total number of errors encountered while transmitting packets. This list includes errors due to the transmission being aborted, errors due to the carrier, etc.
+ *    - rxDropped: Total number of incoming packets dropped.
+ *    - txDropped: Total number of outgoing packets dropped.
+ */
 class NetworkMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
   val receivedBytes = DiffRecordingHistogram(histogram("rx-bytes", Memory.Bytes))
   val transmittedBytes = DiffRecordingHistogram(histogram("tx-bytes", Memory.Bytes))
@@ -34,7 +43,7 @@ class NetworkMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends
   def sumOfAllInterfaces(sigar: Sigar, thunk: NetInterfaceStat ⇒ Long): Long = Try {
     interfaces.map(i ⇒ thunk(sigar.getNetInterfaceStat(i))).fold(0L)(_ + _)
 
-  } getOrElse (0L)
+  } getOrElse 0L
 
   def update(): Unit = {
     receivedBytes.record(sumOfAllInterfaces(sigar, _.getRxBytes))
diff --git a/kamon-system-metrics/src/main/scala/kamon/system/sigar/ProcessCpuMetrics.scala b/kamon-system-metrics/src/main/scala/kamon/system/sigar/ProcessCpuMetrics.scala
index 73dcc6dc..4432e6cd 100644
--- a/kamon-system-metrics/src/main/scala/kamon/system/sigar/ProcessCpuMetrics.scala
+++ b/kamon-system-metrics/src/main/scala/kamon/system/sigar/ProcessCpuMetrics.scala
@@ -20,6 +20,12 @@ import kamon.metric.GenericEntityRecorder
 import kamon.metric.instrument.InstrumentFactory
 import org.hyperic.sigar.{ ProcCpu, Sigar }
 
+/**
+ *  Process Cpu usage metrics, as reported by Sigar:
+ *    - user:  Process cpu user time.
+ *    - total: Process cpu time (sum of User and Sys).
+ *    - system: Process cpu kernel time.
+ */
 class ProcessCpuMetrics(sigar: Sigar, instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) with SigarMetric {
   val processUserCpu = histogram("process-user-cpu")
   val processSystemCpu = histogram("process-system-cpu")