9 files changed, 472 insertions, 0 deletions
diff --git a/doc/01-About.md b/doc/01-About.md
new file mode 100644
index 0000000..01e012f
--- /dev/null
+++ b/doc/01-About.md
@@ -0,0 +1,19 @@
+# Icinga Web Graphite Integration
+
+This module integrates an existing [Graphite](https://graphite.readthedocs.io/en/latest/)
+installation in your [Icinga Web](https://icinga.com/products/infrastructure-monitoring/)
+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)
+* [Troubleshooting](05-Troubleshooting.md)
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
new file mode 100644
index 0000000..6850ecd
--- /dev/null
+++ b/doc/02-Installation.md
@@ -0,0 +1,48 @@
+<!-- {% if index %} -->
+# Installing Icinga Web Graphite Integration
+
+It is recommended to use prebuilt packages
+for all supported platforms from our official release repository.
+Of course [Icinga Web](https://icinga.com/docs/icinga-web) itself
+is required to run its Graphite integration.
+The latter uses Graphite Web, so that is required as well.
+If they are not already set up, it is best to do this first.
+
+The following steps will guide you through installing
+and setting up Icinga Web Graphite Integration.
+<!-- {% else %} -->
+<!-- {% if not icingaDocs %} -->
+
+## Installing the Package
+
+If the [repository](https://packages.icinga.com) is not configured yet, please add it first.
+Then use your distribution's package manager to install the `icinga-graphite` package
+or install [from source](02-Installation.md.d/From-Source.md).
+<!-- {% endif %} --><!-- {# end if not icingaDocs #} -->
+
+## Prepare Icinga 2
+
+Enable the graphite feature:
+
+```
+# icinga2 feature enable graphite
+```
+
+Adjust its configuration in `/etc/icinga2/features-enabled/graphite.conf`:
+
+```
+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.
+
+## Configuring the Icinga Web Graphite Integration
+
+For required additional steps see the [Configuration](03-Configuration.md) chapter.
+<!-- {% endif %} --><!-- {# end else if index #} -->
diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md
new file mode 100644
index 0000000..1433743
--- /dev/null
+++ b/doc/02-Installation.md.d/From-Source.md
@@ -0,0 +1,14 @@
+# Installing Icinga Web Graphite Integration from Source
+
+Please see the Icinga Web documentation on
+[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source.
+Make sure you use `graphite` as the module name. The following requirements must also be met.
+
+## Requirements
+
+* PHP (≥7.2)
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9)
+* [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0)
+* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.9)
+* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11)
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md
new file mode 100644
index 0000000..0b2a38d
--- /dev/null
+++ b/doc/03-Configuration.md
@@ -0,0 +1,65 @@
+# <a id="Configuration"></a>Configuration
+
+## Basics
+
+Open up the Icinga Web 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 frontend and navigate to:
+
+`Configuration > Modules > graphite > Advanced`
+
+### UI
+
+The settings *Default time range* and *Default time range unit* set the default
+time range for displayed graphs both in the graphs lists and in monitored
+objects' detail views.
+
+If you'd like to suppress the *No graphs found* messages, check *Disable "no
+graphs found"*. (This may cause unexpected blank pages in the graphs lists.)
+
+### Icinga 2 (Core)
+
+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))
+
+The setting *Obscured check command custom variable* is only required if there
+are wrapped check commands (see below) and the "actual" check command is stored
+in another custom variable than `check_command`.
+
+## Wrapped check commands
+
+If a monitored object is checked remotely and not via an Icinga 2 agent, but
+e.g. by check_by_ssh or check_nrpe, the monitored object's effective check
+command becomes by_ssh or nrpe respectively. This breaks the respective
+monitored objects' graphs as graph templates are applied to monitored objects
+via their check commands. (They fall back to the default template.)
+
+To make the respective graphs working as expected you have to tell the
+monitored object's "actual" check command by setting its custom variable
+`check_command`, e.g.:
+
+```
+apply Service "by_ssh-disk" {
+  import "generic-service"
+  check_command = "by_ssh"
+  vars.by_ssh_address = "192.0.2.1"
+  vars.by_ssh_command = "/usr/lib64/nagios/plugins/check_disk -w 20 -c 10"
+  vars.check_command = "disk"    // <= HERE
+  assign where host.name == NodeName
+}
+```
+
+## Further reading
+
+* [Templates](04-Templates.md)
+* [Troubleshooting](05-Troubleshooting.md)
diff --git a/doc/04-Templates.md b/doc/04-Templates.md
new file mode 100644
index 0000000..5acbae1
--- /dev/null
+++ b/doc/04-Templates.md
@@ -0,0 +1,226 @@
+# Templates <a id="templates"></a>
+
+A template defines what kind of data a graph visualizes, which kind of graph to
+use and its style. Essentially the Icinga Web Graphite Integration is using
+templates to tell Graphite how to render which graphs.
+
+* [Location](04-Templates.md#templates-location)
+* [Structure](04-Templates.md#templates-structure)
+    * [graph](04-Templates.md#templates-structure-graph)
+    * [metric_filters](04-Templates.md#templates-structure-metric-filters)
+    * [urlparams](04-Templates.md#templates-structure-urlparams)
+    * [functions](04-Templates.md#templates-structure-functions)
+* [Example](04-Templates.md#templates-example)
+* [Default Template Settings](04-Templates.md#templates-default-settings)
+
+## Template Location <a id="templates-location"></a>
+
+There are a bunch of templates already included, located in
+the 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.
+
+## Template Structure <a id="templates-structure"></a>
+
+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:
+
+> **Note:**
+>
+> Template file will be ignored if the [graph] or [metric_filters] section is missing.
+
+### Template Structure: graph <a id="templates-structure-graph"></a>
+
+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.
+
+If multiple check commands do effectively the same thing and yield the same
+perfdata, all of them may be specified separated by comma. E.g.:
+
+```ini
+[ping-rta.graph]
+check_command = "ping, ping4, ping6"
+```
+
+### Template Structure: metric_filters <a id="templates-structure-metric-filters"></a>
+
+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
+
+You can also use wildcards. To define a wildcard, please use the following syntax:
+
+    $macro:wildcard syntax here$
+    
+  Some Examples:
+
+    $perfdata_label:{abc,def}$
+    $perfdata_label:{a*c,de*}$
+    $perfdata_label:{a[vbn]c,def}$
+
+> **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. `$disk$` 
+> is the same as `$disk:*$`.
+
+### Template Structure: urlparams <a id="templates-structure-urlparams"></a>
+
+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$"
+
+You may also define URL parameters once for all templates
+(including the shipped ones) in the `default_url_params` section in
+`/etc/icingaweb2/modules/graphite/config.ini`:
+
+    [default_url_params]
+    yUnitSystem = "none"
+
+These may be overridden in the template itself:
+
+    yUnitSystem = "binary"
+
+### Template Structure: functions <a id="templates-structure-functions"></a>
+
+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)')
+
+In addition you may utilize all other macros here as well:
+
+    alias(color(scale(divideSeries($metric$, $service_name_template$.perfdata.$disk$.max), 100), '#1a7dd7'), 'Used (%)')
+
+## Template Example <a id="templates-example"></a>
+
+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 (%)')"
+```
+
+## Default Template Settings <a id="templates-default-settings"></a>
+
+Next to maintaining templates for specific commands, you can
+specify the default template settings in the [default.ini](https://github.com/Icinga/icingaweb2-module-graphite/blob/master/templates/default.ini)
+configuration file.
+
+The following example adjusts the background and foreground colors
+to setup the "dark mode" for graphs.
+
+First, copy the package provided configuration into the configuration
+path. Then add the `bgcolor` and `fgcolor` settings into the [urlparams](04-Templates.md#templates-structure-urlparams)
+sections for `default-host` and `default-service`.
+
+```
+cp /usr/share/icingaweb2/modules/graphite/templates/default.ini /etc/icingaweb2/modules/graphite/templates/default.ini
+
+vim /etc/icingaweb2/modules/graphite/templates/default.ini
+
+[default-host.urlparams]
+
+bgcolor = "black"
+fgcolor = "white"
+
+[default-service.urlparams]
+
+bgcolor = "black"
+fgcolor = "white"
+```
+
+The settings make use the `urlparams` section which adds the
+parameters to the render API.
+
+
+> **Note**
+>
+> Instead of modifying the color settings in the default template,
+> you can also change the Graphite configuration explained in
+> [this community topic](https://community.icinga.com/t/how-to-adjust-the-graphite-background-color/3172/3).
+
+
+## Further reading
+
+* [Troubleshooting](06-Troubleshooting.md)
diff --git a/doc/05-Troubleshooting.md b/doc/05-Troubleshooting.md
new file mode 100644
index 0000000..11ef711
--- /dev/null
+++ b/doc/05-Troubleshooting.md
@@ -0,0 +1,85 @@
+# <a id="Troubleshooting"></a>Troubleshooting
+
+## Graphs missing or not shown as expected
+
+If too less or too many graphs are shown for a host/service or the graphs don't
+look as expected, debugging becomes harder if there's no obvious error message
+like "Could not resolve host: example.com".
+
+In such cases the "graphs assembling debugger" may help:
+
+1. Navigate to the respective host/service as usual
+2. Add `&graph_debug=1` to the URL
+3. Inspect the log displayed under "Graphs assembling process record"
+
+### Example
+
+Example debug log for the host "icinga.com":
+
+```
++ Icinga check command: 'hostalive'
++ Obscured check command: NULL
++ Applying templates for check command 'hostalive'
+++ Applying template 'hostalive-rta'
++++ Fetched 1 metric(s) from 'https://example.com/metrics/expand?query=icinga2.icinga_com.host.hostalive.perfdata.rta.value'
++++ Excluded 0 metric(s)
++++ Combined 1 metric(s) to 1 chart(s)
+++ Applying template 'hostalive-pl'
++++ Fetched 1 metric(s) from 'https://example.com/metrics/expand?query=icinga2.icinga_com.host.hostalive.perfdata.pl.value'
++++ Excluded 0 metric(s)
++++ Combined 1 metric(s) to 1 chart(s)
++ Applying default templates, excluding previously used metrics
+++ Applying template 'default-host'
++++ Fetched 2 metric(s) from 'https://example.com/metrics/expand?query=icinga2.icinga_com.host.hostalive.perfdata.%2A.value'
++++ Excluded 2 metric(s)
++++ Combined 0 metric(s) to 0 chart(s)
+++ Not applying template 'default-service'
+```
+
+The log describes how the Icinga Web Graphite Integration assembled the
+displayed graphs (or why no graphs could be assembled). The plus signs indent
+the performed actions to visualize their hierarchy, e.g. all actions below
+`Applying templates for check command 'hostalive'` indented with more than one
+plus sign (until `Applying default templates, (...)`) are sub-actions of the
+above one.
+
+#### Details
+
+At first the host's check command is being determined. Then all templates made
+for that check command are applied. Finally, the default template is applied.
+
+For each template the available Graphite metrics are fetched and combined to
+graphs if possible. (See also [Templates](04-Templates.md).) The actual metrics
+are not shown not to make the log too large. But they can be viewed at the shown
+URLs.
+
+Example result of the first URL:
+
+```
+{"results": ["icinga2.icinga_com.host.hostalive.perfdata.rta.value"]}
+```
+
+## Special chars in host or service name
+
+Graphite cannot work with special characters. The host and service name should
+therefore only contain Latin characters. If you want to use special characters
+in host and service names, please set a `display_name` for the object.
+
+### Example
+
+```
+object Host "Only latin chars here" {
+  display_name = "Special chars are welcome"
+  ...
+}
+
+object Service "Only latin chars here" {
+  display_name = "Special chars are welcome"
+  ...
+}
+
+apply Service "Only latin chars here" {
+  display_name = "Special chars are welcome"
+  ...
+}
+```
diff --git a/doc/06-Development.md b/doc/06-Development.md
new file mode 100644
index 0000000..bfa2a57
--- /dev/null
+++ b/doc/06-Development.md
@@ -0,0 +1,15 @@
+# Development
+
+There is a CLI command for demonstrating
+graph templates (useful for developing them):
+
+```bash
+icingacli graphite icinga2 config
+```
+
+It generates Icinga 2 config based on the present graph templates.
+With this config Icinga will (also) "monitor" dummy services yielding random
+perfdata as expected by the graph templates.
+
+I. e.: If that Icinga is also writing to the Graphite that is read by your
+Icinga Web Graphite Integration, you'll get dummy graphs for all templates.
diff --git a/doc/img/service-detail-view.png b/doc/img/service-detail-view.png
new file mode 100644
index 0000000..807524b
--- /dev/null
+++ b/doc/img/service-detail-view.png
diff --git a/doc/img/service-list.png b/doc/img/service-list.png
new file mode 100644
index 0000000..b234068
--- /dev/null
+++ b/doc/img/service-list.png