diff --git a/doc/14-features.md b/doc/14-features.md index eb6c231b3..6a7511bac 100644 --- a/doc/14-features.md +++ b/doc/14-features.md @@ -358,6 +358,82 @@ Currently these events are processed: * State changes * Notifications +### 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. + ### OpenTSDB Writer While there are some OpenTSDB collector scripts and daemons like tcollector available for diff --git a/doc/9-object-types.md b/doc/9-object-types.md index 671341e7e..61586c5ae 100644 --- a/doc/9-object-types.md +++ b/doc/9-object-types.md @@ -1009,6 +1009,31 @@ Configuration Attributes: > > UNIX sockets are not supported on Windows. +## 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`. + ## Notification