GelfWriter: Add documentation

refs #7619

diff --git a/doc/1-about.md b/doc/1-about.md
index 6a6e93fa5f1f1608446bd5169c488d3469b08437..95ea33039c0bcf232975f08d365f550bf76a5331 100644 (file)
--- a/doc/1-about.md
+++ b/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

diff --git a/doc/4-monitoring-basics.md b/doc/4-monitoring-basics.md
index fcca50ba2914f26b4a353f2a26221d33218a8bc2..fdf8e278e80d6c07ced941a1965113a717a3c88f 100644 (file)
--- a/doc/4-monitoring-basics.md
+++ b/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

diff --git a/doc/7-configuring-icinga-2.md b/doc/7-configuring-icinga-2.md
index b883cf8084f080f1fe1c1de8f1da5179bf140d06..0b23d293382a34ad25cdc5601066d129e02d01cb 100644 (file)
--- a/doc/7-configuring-icinga-2.md
+++ b/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.

diff --git a/etc/icinga2/features-available/gelf.conf b/etc/icinga2/features-available/gelf.conf
index a9d180b513973ca0417a07c55c3ecd6c2a67491f..43ea7aae55a2fa1f97c06c9f58a0f3d5fc55d84c 100644 (file)
--- a/etc/icinga2/features-available/gelf.conf
+++ b/etc/icinga2/features-available/gelf.conf
@@ -1,11 +1,12 @@
 /**
- * The GelfWriter type writes event logs
- * to a gelf tcp socket provided by graylog2.
+ * The GelfWriter type writes event log entries
+ * 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
 }