1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
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/main/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)
|
