Add documentation for the LogstashWriter feature

This includes Logstash and Icinga 2 configuration.

refs #4054

doc/14-features.md

@@ -358,6 +358,82 @@ Currently these events are processed:
 * State changes
 * Notifications
 
+### <a id="logstash-writer"></a> Logstash Writer
+
+[Logstash](https://www.elastic.co/products/logstash) receives
+and processes event messages sent by Icinga 2 and the [LogstashWriter](9-object-types.md#objecttype-logstashwriter)
+feature. As part of the Elastic Stack it allows you to
+process and modify the messages and forward them to [Elasticsearch](https://www.elastic.co/products/elasticsearch)
+as backed.
+
+Before proceeding with this integration guide please ensure
+that you have Logstash, Elasticsearch and Kibana up and running
+as part of the Elastic Stack.
+
+> **Note**
+>
+> The LogstashWriter feature has been tested with Elastic Stack 5.x and therefore Logstash 5.x.
+> Older versions are not supported.
+
+Logstash supports `TCP` and `UDP` as input socket type. You must
+further enable JSON support for input data processing. Logstash 5.x
+comes without any pre-installed plugins and requires you to install
+them separately.
+
+Example on CentOS 7 and UDP as socket type:
+
+```
+/usr/share/logstash/bin/logstash-plugin install logstash-input-udp
+/usr/share/logstash/bin/logstash-plugin install logstash-input-json
+```
+
+Add the Icinga 2 input and set the output to your running Elasticsearch instance.
+You do not need to reload Logstash since version 5.x supports configuration changes
+without restart.
+
+This example uses port `5555`. You are allowed to use any available port (note it for later).
+
+```
+# vim /etc/logstash/conf.d/icinga2.conf
+
+input {
+  udp {
+    port => 5555
+    codec => "json"
+  }
+}
+output {
+  elasticsearch {
+    hosts => [ "localhost:9200" ]
+  }
+}
+```
+
+Modify the feature configuration and set the
+socket type, host and port attributes. The port must be the same
+as configured in your Logstash input, e.g. `5555`.
+
+```
+# vim /etc/icinga2/features-available/logstash.conf
+
+object LogstashWriter "logstash" {
+  host = "192.168.33.7"
+  port = 5555
+  socket_type = "udp"
+}
+```
+
+Enable the feature and restart Icinga 2.
+
+```
+# icinga2 feature enable logstash
+# systemctl restart icinga2
+```
+
+Open [Kibana](https://www.elastic.co/products/kibana) or your
+favorite Elasticsearch frontend and visualize the messages received
+from Icinga 2.
+
 ### <a id="opentsdb-writer"></a> OpenTSDB Writer
 
 While there are some OpenTSDB collector scripts and daemons like tcollector available for

doc/9-object-types.md

@@ -1009,6 +1009,31 @@ Configuration Attributes:
 >
 > UNIX sockets are not supported on Windows.
 
+## <a id="objecttype-logstashwriter"></a> LogstashWriter
+
+Writes Icinga 2 event messages to [Logstash](14-features.md#logstash-writer).
+
+Example:
+
+```
+library "perfdata"
+
+object LogstashWriter "logstash" {
+  host = "192.168.33.7"
+  port = 5555
+  socket_type = "udp"
+}
+```
+
+Configuration Attributes:
+
+  Name            	|Description
+  ----------------------|----------------------
+  host            	|**Optional.** Logstash receiver host address. Defaults to `127.0.0.1`.
+  port            	|**Optional.** Logstash receiver port. Defaults to `9201`.
+  socket_type		|**Optional.** Socket type. Can be either `udp` or `tcp`. Defaults to `udp`.
+  source		|**Optional.** Source name for this instance. Defaults to `icinga2`.
+
 
 ## <a id="objecttype-notification"></a> Notification