Added jolokia README.md

closes #337

CHANGELOG.md

@@ -12,6 +12,7 @@ changed to just run docker commands in the Makefile. See `make docker-run` and
 - [#325](https://github.com/influxdb/telegraf/pull/325): NSQ output. Thanks @jrxFive!
 - [#318](https://github.com/influxdb/telegraf/pull/318): Prometheus output. Thanks @oldmantaiter!
 - [#338](https://github.com/influxdb/telegraf/pull/338): Restart Telegraf on package upgrade. Thanks @linsomniac!
+- [#337](https://github.com/influxdb/telegraf/pull/337): Jolokia plugin, thanks @saiello!
 
 ### Bugfixes
 - [#331](https://github.com/influxdb/telegraf/pull/331): Dont overwrite host tag in redis plugin.

README.md

@@ -173,6 +173,7 @@ Telegraf currently has support for collecting metrics from:
 * exec (generic JSON-emitting executable plugin)
 * haproxy
 * httpjson (generic JSON-emitting http service plugin)
+* jolokia (remote JMX with JSON over HTTP)
 * kafka_consumer
 * leofs
 * lustre2

plugins/jolokia/README.md

@@ -0,0 +1,51 @@
+# Telegraf plugin: Jolokia
+
+#### Plugin arguments:
+- **context** string: Context root used of jolokia url
+- **servers** []Server: List of servers
+  + **name** string: Server's logical name
+  + **host** string: Server's ip address or hostname
+  + **port** string: Server's listening port
+- **metrics** []Metric
+  + **name** string: Name of the measure
+  + **jmx** string: Jmx path that identifies mbeans attributes
+  + **pass** []string: Attributes to retain when collecting values
+  + **drop** []string: Attributes to drop when collecting values
+
+#### Description
+
+The Jolokia plugin collects JVM metrics exposed as MBean's attributes through jolokia REST endpoint. All metrics
+are collected for each server configured.
+
+See: https://jolokia.org/
+
+# Measurements:
+Jolokia plugin produces one measure for each metric configured, adding Server's `name`, `host` and `port` as tags.
+
+Given a configuration like:
+
+```ini
+[jolokia]
+
+[[jolokia.servers]]
+  name = "as-service-1"
+  host = "127.0.0.1"
+  port = "8080"
+
+[[jolokia.servers]]
+  name = "as-service-2"
+  host = "127.0.0.1"
+  port = "8180"
+
+[[jolokia.metrics]]
+  name = "heap_memory_usage"
+  jmx  = "/java.lang:type=Memory/HeapMemoryUsage"
+  pass = ["used", "max"]
+```
+
+The collected metrics will be:
+
+```
+jolokia_heap_memory_usage name=as-service-1,host=127.0.0.1,port=8080 used=xxx,max=yyy
+jolokia_heap_memory_usage name=as-service-2,host=127.0.0.1,port=8180 used=vvv,max=zzz
+```

plugins/jolokia/jolokia.go

@@ -8,7 +8,6 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
-	// "sync"
 
 	"github.com/influxdb/telegraf/plugins"
 )
@@ -48,31 +47,42 @@ type Jolokia struct {
 
 func (j *Jolokia) SampleConfig() string {
 	return `
+	# This is the context root used to compose the jolokia url
   context = "/jolokia/read"
 
+	# Tags added to each measurements
 	[jolokia.tags]
 		group = "as"
 
+	# List of servers exposing jolokia read service
   [[jolokia.servers]]
-        name = "stable"
-        host = "192.168.103.2"
-        port = "8180"
+    name = "stable"
+    host = "192.168.103.2"
+    port = "8180"
 
+	# List of metrics collected on above servers
+	# Each metric consists in a name, a jmx path and either a pass or drop slice attributes
+	# This collect all heap memory usage metrics
   [[jolokia.metrics]]
-        name = "heap_memory_usage"
-        jmx  = "/java.lang:type=Memory/HeapMemoryUsage"
-        pass = ["used"]
+    name = "heap_memory_usage"
+    jmx  = "/java.lang:type=Memory/HeapMemoryUsage"
 
-  [[jolokia.metrics]]
-        name = "memory_eden"
-        jmx  = "/java.lang:type=MemoryPool,name=PS Eden Space/Usage"
-        pass = ["used"]
 
+  # This drops the 'committed' value from Eden space measurement
   [[jolokia.metrics]]
-        name = "heap_threads"
-        jmx  = "/java.lang:type=Threading"
- #      drop = ["AllThread"]
-        pass = ["CurrentThreadCpuTime","CurrentThreadUserTime","DaemonThreadCount","ThreadCount","TotalStartedThreadCount"]
+    name = "memory_eden"
+    jmx  = "/java.lang:type=MemoryPool,name=PS Eden Space/Usage"
+    drop = [ "committed" ]
+
+
+	# This passes only DaemonThreadCount and ThreadCount
+  [[jolokia.metrics]]
+		name = "heap_threads"
+    jmx  = "/java.lang:type=Threading"
+    pass = [
+			"DaemonThreadCount",
+			"ThreadCount"
+		]
 `
 }