GelfWriter: Add documentation

refs #7619

doc/1-about.md

@@ -62,6 +62,8 @@ Icinga 2 is available as [Vagrant Demo VM](#vagrant).
     * schema files in `lib/db_ido_{mysql,pgsql}/schema` (source)
     * Table `programstatus`: New column `program_version`
     * Table `customvariables` and `customvariablestatus`: New column `is_json` (required for custom attribute array/dictionary support)
+* New features
+    * [GelfWriter](#gelfwriter): Logging check results, state changes, notifications to GELF (graylog2, logstash) #7619
 * New CLI commands #7245
     * `icinga2 feature {enable,disable}` replaces `icinga2-{enable,disable}-feature` script  #7250
     * `icinga2 object list` replaces `icinga2-list-objects` script  #7251
@@ -162,6 +164,12 @@ Icinga 2 still supports writing performance data files for graphing addons, but
 capability of writing performance data directly into a Graphite TCP socket simplifying realtime
 monitoring graphs.
 
+* Native support for writing log events to [GELF](#gelf-writer) receivers (graylog2, Logstash)
+
+Icinga 2 will write all check result, state change and notification event logs into a defined
+[GELF](#gelfwriter) input receiver. Natively provided by [graylog2](http://www.graylog2.org),
+and as additional input type provided by [Logstash](http://logstash.net).
+
 * Dynamic configuration language
 
 Simple [apply](#using-apply) and [assign](#group-assign) rules for creating configuration object

doc/4-monitoring-basics.md

@@ -2171,7 +2171,7 @@ You can enable the feature using
     # icinga2 feature enable graphite
 
 By default the `GraphiteWriter` object expects the Graphite Carbon Cache to listen at
-`127.0.0.1` on port `2003`.
+`127.0.0.1` on TCP port `2003`.
 
 The current naming schema is
 
@@ -2228,6 +2228,29 @@ Cache. Please make sure that the order is correct because the first match wins.
     pattern = ^icinga\.
     retentions = 1m:2d,5m:10d,30m:90d,360m:4y
 
+### <a id="gelfwriter"></a> GELF Writer
+
+The `Graylog Extended Log Format` (short: [GELF](http://www.graylog2.org/resources/gelf))
+can be used to send application logs directly to a TCP socket.
+
+While it has been specified by the [graylog2](http://www.graylog2.org/) project as their
+[input resource standard](http://www.graylog2.org/resources/gelf), other tools such as
+[Logstash](http://www.logstash.net) also support `GELF` as
+[input type](http://logstash.net/docs/latest/inputs/gelf).
+
+You can enable the feature using
+
+    # icinga2 feature enable gelf
+
+By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
+The default `source`  attribute is set to `icinga2`. You can customize that for your needs if required.
+
+Currently these events are processed:
+* Check results
+* State changes
+* Notifications
+
+
 ## <a id="status-data"></a> Status Data
 
 Icinga 1.x writes object configuration data and status data in a cyclic

doc/7-configuring-icinga-2.md

@@ -1335,6 +1335,28 @@ Example with your custom [global constant](#global-constants) `GraphiteEnv`:
     host_name_template = GraphiteEnv + ".$host.name$"
     service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
 
+### <a id="objecttype-gelfwriter"></a> GelfWriter
+
+Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
+
+Example:
+
+    library "perfdata"
+
+    object GelfWriter "gelf" {
+      host = "127.0.0.1"
+      port = 12201
+    }
+
+Attributes:
+
+  Name            	|Description
+  ----------------------|----------------------
+  host            	|**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
+  port            	|**Optional.** GELF receiver port. Defaults to `12201`.
+  source		|**Optional.** Source name for this instance. Defaults to `icinga2`.
+
+
 ### <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
 
 IDO database adapter for MySQL.

etc/icinga2/features-available/gelf.conf

@@ -1,11 +1,12 @@
 /**
- * The GelfWriter type writes event logs
+ * The GelfWriter type writes event log entries
- * to a gelf tcp socket provided by graylog2.
+ * to a GELF tcp socket provided by graylog2,
+ * logstash or any other receiver.
  */
 
 library "perfdata"
 
-object GelfWriter "graylog2" {
+object GelfWriter "gelf" {
   //host = "127.0.0.1"
   //port = 12201
 }