diff options
Diffstat (limited to 'doc/04-Templates.md')
| -rw-r--r-- | doc/04-Templates.md | 226 |
1 files changed, 226 insertions, 0 deletions
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) |