Rewriting Riemann output plugin (#1900)

* rename to riemann_legacy

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* initial draft for Riemann output plugin rewrite

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* add unit tests

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* add option to send string metrics as states

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* add integration tests

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* add plugin README.md

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* bump riemann library

* clarify settings description

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* update Readme.md with updated description

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* add Riemann event examples

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

* use full URL for Riemann server address

Signed-off-by: Fabio Berchtold <fabio.berchtold@swisscom.com>

closes #1878

Godeps

@@ -1,7 +1,7 @@
 github.com/Shopify/sarama 8aadb476e66ca998f2f6bb3c993e9a2daa3666b9
 github.com/Sirupsen/logrus 219c8cb75c258c552e999735be6df753ffc7afdc
 github.com/aerospike/aerospike-client-go 7f3a312c3b2a60ac083ec6da296091c52c795c63
-github.com/amir/raidman 53c1b967405155bfc8758557863bf2e14f814687
+github.com/amir/raidman c74861fe6a7bb8ede0a010ce4485bdbb4fc4c985
 github.com/aws/aws-sdk-go 13a12060f716145019378a10e2806c174356b857
 github.com/beorn7/perks 3ac7bf7a47d159a033b107610db8a1b6575507a4
 github.com/cenkalti/backoff 4dc77674aceaabba2c7e3da25d4c823edfb73f99

Makefile

@@ -58,7 +58,7 @@ docker-run:
 	docker run --name redis -p "6379:6379" -d redis
 	docker run --name nsq -p "4150:4150" -d nsqio/nsq /nsqd
 	docker run --name mqtt -p "1883:1883" -d ncarlier/mqtt
-	docker run --name riemann -p "5555:5555" -d blalor/riemann
+	docker run --name riemann -p "5555:5555" -d stealthly/docker-riemann
 	docker run --name nats -p "4222:4222" -d nats
 
 # Run docker containers necessary for CircleCI unit tests
@@ -71,7 +71,7 @@ docker-run-circle:
 		-d spotify/kafka
 	docker run --name nsq -p "4150:4150" -d nsqio/nsq /nsqd
 	docker run --name mqtt -p "1883:1883" -d ncarlier/mqtt
-	docker run --name riemann -p "5555:5555" -d blalor/riemann
+	docker run --name riemann -p "5555:5555" -d stealthly/docker-riemann
 	docker run --name nats -p "4222:4222" -d nats
 
 # Kill all docker containers, ignore errors

README.md

@@ -219,6 +219,7 @@ Telegraf can also collect metrics via the following service plugins:
 * [opentsdb](./plugins/outputs/opentsdb)
 * [prometheus](./plugins/outputs/prometheus_client)
 * [riemann](./plugins/outputs/riemann)
+* [riemann_legacy](./plugins/outputs/riemann_legacy)
 
 ## Contributing
 

etc/telegraf.conf

@@ -443,8 +443,39 @@
 #   # expiration_interval = "60s"
 
 
-# # Configuration for the Riemann server to send metrics to
+# # Configuration for Riemann server to send metrics to
 # [[outputs.riemann]]
+#   ## The full TCP or UDP URL of the Riemann server
+#   url = "tcp://localhost:5555"
+#
+#   ## Riemann event TTL, floating-point time in seconds.
+#   ## Defines how long that an event is considered valid for in Riemann
+#   # ttl = 30.0
+#
+#   ## Separator to use between measurement and field name in Riemann service name
+#   ## This does not have any effect if 'measurement_as_attribute' is set to 'true'
+#   separator = "/"
+#
+#   ## Set measurement name as Riemann attribute 'measurement', instead of prepending it to the Riemann service name
+#   # measurement_as_attribute = false
+#
+#   ## Send string metrics as Riemann event states.
+#   ## Unless enabled all string metrics will be ignored
+#   # string_as_state = false
+#
+#   ## A list of tag keys whose values get sent as Riemann tags.
+#   ## If empty, all Telegraf tag values will be sent as tags
+#   # tag_keys = ["telegraf","custom_tag"]
+#
+#   ## Additional Riemann tags to send.
+#   # tags = ["telegraf-output"]
+#
+#   ## Description for Riemann event
+#   # description_text = "metrics collected from telegraf"
+
+
+# # Configuration for the legacy Riemann plugin
+# [[outputs.riemann_legacy]]
 #   ## URL of server
 #   url = "localhost:5555"
 #   ## transport protocol to use either tcp or udp

plugins/outputs/all/all.go

@@ -20,4 +20,5 @@ import (
 	_ "github.com/influxdata/telegraf/plugins/outputs/opentsdb"
 	_ "github.com/influxdata/telegraf/plugins/outputs/prometheus_client"
 	_ "github.com/influxdata/telegraf/plugins/outputs/riemann"
+	_ "github.com/influxdata/telegraf/plugins/outputs/riemann_legacy"
 )

plugins/outputs/riemann/README.md

@@ -0,0 +1,83 @@
+# Riemann Output Plugin
+
+This plugin writes to [Riemann](http://riemann.io/) via TCP or UDP.
+
+### Configuration:
+
+```toml
+# Configuration for Riemann to send metrics to
+[[outputs.riemann]]
+  ## The full TCP or UDP URL of the Riemann server
+  url = "tcp://localhost:5555"
+
+  ## Riemann event TTL, floating-point time in seconds.
+  ## Defines how long that an event is considered valid for in Riemann
+  # ttl = 30.0
+
+  ## Separator to use between measurement and field name in Riemann service name
+  ## This does not have any effect if 'measurement_as_attribute' is set to 'true'
+  separator = "/"
+
+  ## Set measurement name as Riemann attribute 'measurement', instead of prepending it to the Riemann service name
+  # measurement_as_attribute = false
+
+  ## Send string metrics as Riemann event states.
+  ## Unless enabled all string metrics will be ignored
+  # string_as_state = false
+
+  ## A list of tag keys whose values get sent as Riemann tags.
+  ## If empty, all Telegraf tag values will be sent as tags
+  # tag_keys = ["telegraf","custom_tag"]
+
+  ## Additional Riemann tags to send.
+  # tags = ["telegraf-output"]
+
+  ## Description for Riemann event
+  # description_text = "metrics collected from telegraf"
+```
+
+### Required parameters:
+
+* `url`: The full TCP or UDP URL of the Riemann server to send events to.
+
+### Optional parameters:
+
+* `ttl`: Riemann event TTL, floating-point time in seconds. Defines how long that an event is considered valid for in Riemann.
+* `separator`: Separator to use between measurement and field name in Riemann service name.
+* `measurement_as_attribute`: Set measurement name as a Riemann attribute, instead of prepending it to the Riemann service name.
+* `string_as_state`: Send string metrics as Riemann event states. If this is not enabled then all string metrics will be ignored.
+* `tag_keys`: A list of tag keys whose values get sent as Riemann tags. If empty, all Telegraf tag values will be sent as tags.
+* `tags`: Additional Riemann tags that will be sent.
+* `description_text`: Description text for Riemann event.
+
+### Example Events:
+
+Riemann event emitted by Telegraf with default configuration:
+```
+#riemann.codec.Event{
+:host "postgresql-1e612b44-e92f-4d27-9f30-5e2f53947870", :state nil, :description nil, :ttl 30.0,
+:service "disk/used_percent", :metric 73.16736001949994, :path "/boot", :fstype "ext4", :time 1475605021}
+```
+
+Telegraf emitting the same Riemann event with `measurement_as_attribute` set to `true`:
+```
+#riemann.codec.Event{ ...
+:measurement "disk", :service "used_percent", :metric 73.16736001949994,
+... :time 1475605021}
+```
+
+Telegraf emitting the same Riemann event with additional Riemann tags defined:
+```
+#riemann.codec.Event{
+:host "postgresql-1e612b44-e92f-4d27-9f30-5e2f53947870", :state nil, :description nil, :ttl 30.0,
+:service "disk/used_percent", :metric 73.16736001949994, :path "/boot", :fstype "ext4", :time 1475605021,
+:tags ["telegraf" "postgres_cluster"]}
+```
+
+Telegraf emitting a Riemann event with a status text and `string_as_state` set to `true`, and a `description_text` defined:
+```
+#riemann.codec.Event{
+:host "postgresql-1e612b44-e92f-4d27-9f30-5e2f53947870", :state "Running", :ttl 30.0,
+:description "PostgreSQL master node is up and running",
+:service "status", :time 1475605021}
+```