Merge branch 'feature/add-documentation-67'

fixes #67

README.md

@@ -1,76 +1,20 @@
-# Graphite module for Icinga Web 2
+# Graphite - Icinga Web 2 Module
 
-## General Information
+![Icinga Logo](https://www.icinga.com/wp-content/uploads/2014/06/icinga_logo.png)
 
-This module integrates an existing [Graphite](https://graphite.readthedocs.org/en/latest/)
-installation in your
-[Icinga Web 2](https://www.icinga.org/icinga/screenshots/icinga-web-2/) web
+This module integrates an existing [Graphite](https://graphite.readthedocs.io/en/latest/)
+installation in your [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/)
 frontend.
 
-## Features
+![Service List](doc/img/service-list.png) | ![Detail View](doc/img/service-detail-view.png)
+------------------------------------------|------------------------------------------------
 
-* Global overview underneath `History / Graphite` menu section
-* Detail view actions: render graphs for hosts and services
+It provides a new menu section with two general overviews for hosts and
+services as well as an extension to the host and service detail view of
+the monitoring module.
 
-## Requirements
-
-* Icinga Web 2 v2.1.0
-* Icinga 2 v2.4.0 using the new Graphite tree in ([#9461](https://dev.icinga.org/issues/9461)).
-* Graphite and Graphite Web
-
-## Prepare Icinga2
-
-Enable the graphite feature:
-
-    icinga2 feature enable graphite
-
-Adjust it's configuration in `/etc/icinga2/features-enabled/graphite.conf`:
-
-```
-library "perfdata"
-
-object GraphiteWriter "graphite" {
-  host = "127.0.0.1"
-  port = 2003
-  enable_send_thresholds = true
-}
-```
-
-And then restart Icinga2. Enabling thresholds is not a hard requirement.
-However, some templates look better when they are able to render a max
-values or similar.
-
-## Installation
-
-Just extract/clone this module to a `graphite` subfolder in your Icinga
-Web 2 module path. Enable the graphite module in your Icinga Web 2 frontend
-(*Configuration* > *Modules* > *graphite* > *enable*).
-
-NB: It is best practice to install 3rd party modules into a distinct module
-folder for example `/usr/share/icingaweb2/modules`. In case you don't know where this
-might be please check the module path in your Icinga Web 2 configuration.
-
-## Configuration
-
-Open Icinga Web 2 (web UI) and navigate to *Configuration* > *Modules* >
-*graphite* > *Backend*. Fill in the Graphite Web root URL
-(e.g. `http://192.0.2.1:8003/`) and the HTTP basic auth credentials (if any).
-
-You don't need any configuration in your Icinga 2 installation (e.g.
-additional custom vars).
-
-## Testdrive
-
-Icinga 2 and Graphite feature enabled:
-
-    icinga2 feature enable graphite
-
-Graphite and Graphite Web running, e.g. as docker instance:
-
-    sudo docker run -d --name graphite --restart=always -p 9090:80 -p 2003:2003 hopsoft/graphite-statsd
-
-Icinga Web 2 with Graphite module enabled
-
-    [graphite]
-    web_url = http://localhost:9090
+## Documentation
 
+* [Installation](doc/02-Installation.md)
+* [Configuration](doc/03-Configuration.md)
+* [Templates](doc/04-Templates.md)

doc/01-About.md

@@ -0,0 +1,18 @@
+# Graphite - Icinga Web 2 Module
+
+This module integrates an existing [Graphite](https://graphite.readthedocs.io/en/latest/)
+installation in your [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/)
+frontend.
+
+![Service List](img/service-list.png) | ![Detail View](img/service-detail-view.png)
+--------------------------------------|--------------------------------------------
+
+It provides a new menu section with two general overviews for hosts and
+services as well as an extension to the host and service detail view of
+the monitoring module.
+
+## Documentation
+
+* [Installation](02-Installation.md)
+* [Configuration](03-Configuration.md)
+* [Templates](04-Templates.md)

doc/02-Installation.md

@@ -0,0 +1,42 @@
+# <a id="Installation"></a>Installation
+
+## Requirements
+
+* Icinga 2 (>= 2.4.0)
+* Icinga Web 2 (>= 2.5.0)
+* Graphite and Graphite Web
+
+## Prepare Icinga 2
+
+Enable the graphite feature:
+
+    # icinga2 feature enable graphite
+
+Adjust its configuration in `/etc/icinga2/features-enabled/graphite.conf`:
+
+```
+library "perfdata"
+
+object GraphiteWriter "graphite" {
+  host = "192.0.2.42"
+  port = 2003
+  enable_send_thresholds = true
+}
+```
+
+And then restart Icinga2. Enabling thresholds is not a hard requirement.
+However, some templates look better if they are able to render a max
+value or similar.
+
+## Setup the Graphite Module
+
+Just extract/clone this module to a `graphite` subfolder in your Icinga Web 2
+module path and enable it in the frontend.
+(*Configuration* > *Modules* > *graphite* > *enable*)
+
+> **Note:**
+>
+> It is best practice to install 3rd party modules into a distinct module
+> folder for example `/usr/share/icingaweb2/modules`. In case you do not
+> know where this might be please check the module path in your Icinga Web 2
+> configuration.

doc/03-Configuration.md

@@ -0,0 +1,22 @@
+# <a id="Configuration"></a>Configuration
+
+## Basics
+
+Open up the Icinga Web 2 frontend and navigate to:
+
+    Configuration > Modules > graphite > Backend
+
+Enter the Graphite Web URL. (e.g. `https://192.0.2.42:8003/`)
+
+The HTTP basic authentication credentials are only required
+if your Graphite Web is protected by such a mechanism.
+
+## Advanced
+
+Open up the Icinga Web 2 frontend and navigate to:
+
+    Configuration > Modules > graphite > Advanced
+
+The settings *Host name template* and *Service name template* both are only
+required if you are using a different naming schema than the default Icinga 2
+is using. (As outlined [here](https://www.icinga.com/docs/icinga2/latest/doc/14-features/#current-graphite-schema))

doc/04-Templates.md

@@ -0,0 +1,135 @@
+# <a id="Templates"></a>Templates
+
+A template defines what kind of data a graph visualizes, which kind of graph to
+use and its style. Essentially this module is using templates to tell Graphite
+how to render which graphs.
+
+## Template Location
+
+There are a bunch of templates already shipped with this module, located in
+its installation path. (e.g. `/usr/share/icingaweb2/modules/graphite`)
+
+To add additional/customized templates, place them in its configuration path.
+(e.g. `/etc/icingaweb2/modules/graphite/templates`) These will either extend
+the available templates or override some of them. Subfolders placed here will
+also be included in the same way, while additionally extending or overriding
+templates of its parent folders.
+
+> **Note:**
+>
+> Hidden files and directories (with a leading dot) are ignored by this module.
+
+## Template Structure
+
+Templates are organized within simple INI files. However, it is perfectly valid
+to define multiple templates in a single file.
+
+The name of a section consists of two parts separated by a dot:
+
+    [hostalive-rta.graph]
+
+The first part is the name of the template and the second part the name of one
+of the following configuration topics:
+
+**graph**
+
+Supports a single option called `check_command` and should be set to the name
+of a Icinga 2 [check-command](https://www.icinga.com/docs/icinga2/latest/doc/03-monitoring-basics/#check-commands).  
+To get multiple graphs for hosts and services with this check-command, multiple
+templates can reference the same check-command.
+
+**metrics_filters**
+
+Define what metric to use and how many curves to display in the resulting graph.  
+Each option's key represents the name of a curve. Its value the path to the
+metric in Icinga 2's [graphite naming schema](https://www.icinga.com/docs/icinga2/latest/doc/14-features/#current-graphite-schema).
+
+Curve names are used to map Graphite functions to metrics. (More on this below)
+However, they are fully arbitrary and have no further meaning outside template
+configurations.
+
+A curve's metric path must begin with either the macro `$host_name_template$`
+or `$service_name_template$` and is substituted with Icinga 2's prefix label.
+The rest of the path is arbitrary, but to get meaningful results use a valid
+path to one of the performance data metrics:
+
+    <prefix-label>.perfdata.<perfdata-label>.<metric>
+
+An example path which points to the metric `value` of the `rta` perfdata-label
+looks as follows:
+
+    $host_name_template$.perfdata.rta.value
+
+To dynamically render a graph for each performance data label found, define a
+macro in place for the actual perfdata-label:
+
+    $host_name_template$.perfdata.$perfdata_label$.value
+
+> **Note:**
+>
+> The name of the macro for the perfdata-label is also arbitrary. You may as
+> well use a more descriptive name such as `$disk$` for the disk check.
+
+**urlparams**
+
+Allows to define additional URL parameters to be passed to Graphite's render
+API.
+
+Each option represents a single parameter's name and value. A list of all
+supported parameters can be found [here](https://graphite.readthedocs.io/en/latest/render_api.html#graph-parameters).
+
+If you have used a macro for the curve's perfdata-label you may utilize it
+here as well:
+
+    title = "Disk usage on $disk$"
+
+**functions**
+
+Allows to define Graphite functions which are applied to the metric of a
+specific curve on the graph.
+
+Each option's key must match a curve's name in order to apply the function
+to the curve's metric. A list of all supported functions can be found [here](https://graphite.readthedocs.io/en/latest/functions.html#functions).
+
+The metric in question can be referenced in the function call using the macro
+`$metric$` as shown in the following example:
+
+    alias(color(scale($metric$, 1000), '#1a7dd7'), 'Round trip time (ms)')
+
+## Template Example
+
+The configuration examples used in this document are borrowed from the template
+for the `hostalive` check-command:
+
+```ini
+[hostalive-rta.graph]
+check_command = "hostalive"
+
+[hostalive-rta.metrics_filters]
+rta.value = "$host_name_template$.perfdata.rta.value"
+
+[hostalive-rta.urlparams]
+areaAlpha = "0.5"
+areaMode = "all"
+min = "0"
+yUnitSystem = "none"
+
+[hostalive-rta.functions]
+rta.value = "alias(color(scale($metric$, 1000), '#1a7dd7'), 'Round trip time (ms)')"
+
+
+[hostalive-pl.graph]
+check_command = "hostalive"
+
+[hostalive-pl.metrics_filters]
+pl.value = "$host_name_template$.perfdata.pl.value"
+
+[hostalive-pl.urlparams]
+areaAlpha = "0.5"
+areaMode = "all"
+min = "0"
+yUnitSystem = "none"
+
+[hostalive-pl.functions]
+pl.value = "alias(color($metric$, '#1a7dd7'), 'Packet loss (%)')"
+```