====== What are templates? ======

PNP uses templates to influence the appearance of RRD graphs.

The selected check_command determines which template will be used to control the graph. Following will be described where templates are stored and how the decision for the "right" template is made.



===== What template will be used when? =====

Templates are stored at two places in the file system.

  * share/pnp/templates.dist - for templates included in the PNP package
  * share/pnp/templates - for custom made template which are not changed during updates

If the graph for the service "http" on host "localhost" should be shown, PNP will look for the XML file ''perfdata/localhost/http.xml'' and read its contents. The XML files are created automatically and contain information about the particular host and service. The header contains information about the plugin and the performance data. The XML tag ''<TEMPLATE>'' identifies which PNP template will be used for this graph.

''**/localhost/http.xml**''
<code xml>
<NAGIOS>
  <DATASOURCE>
    <TEMPLATE>check_http</TEMPLATE>
    <DS>1</DS>
    <NAME>time</NAME>
    <UNIT>s</UNIT>
    <ACT>0.006721</ACT>
    <WARN>1.000000</WARN>
    <CRIT>2.000000</CRIT>
    <MIN>0.000000</MIN>
    <MAX></MAX>
  </DATASOURCE>
  <DATASOURCE>
    <TEMPLATE>check_http</TEMPLATE>
    <DS>2</DS>
    <NAME>size</NAME>
    <UNIT>B</UNIT>
    <ACT>263</ACT>
    <WARN></WARN>
    <CRIT></CRIT>
    <MIN>0</MIN>
    <MAX></MAX>
  </DATASOURCE>
...
</NAGIOS>

</code>

PNP will look for a template with the name ''check_http.php'' in the following sequence:

   - templates/check_http.php
   - templates.dist/check_http.php
   - templates/default.php
   - templates.dist/default.php

The template default.php takes an exceptional position as it is used every time no other applicable template is found.



===== Creating own templates =====

PNP templates are PHP files which are included during execution of PNP using the PHP function include(). This means that every PHP code in templates will be interpreted so manipulation of all values is possible.

PNP template must have the following characteristics:

  - templates must contain valid PHP code.
  - templates must not create any output.
  - the two arrays $opt[] and $def[] have to be filled

These two arrays are used to call '''rrdtool graph''' so every option is possible that RRDtool supports. All options of RRDtool are described very thoroughly on the [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html|RRDtool Homepage]].

If both arrays contain more than one set of data graphs will be created for every set.

Inside the templates the data from the related XML files can be used.

Using the relatively simple template response.php we will describe the most important options.

<code php>
<?php
#
$opt[1] = "--title \"Response Time For  $hostname / $servicedesc\" ";
#
$def[1] =  "DEF:var1=$rrdfile:$DS[1]:AVERAGE " ;
$def[1] .= "AREA:var1#00FF00:\"Response Times \" " ;
$def[1] .= "LINE1:var1#000000 " ;
$def[1] .= "GPRINT:var1:LAST:\"%3.4lg %s$UNIT[1] LAST \" ";
$def[1] .= "GPRINT:var1:MAX:\"%3.4lg %s$UNIT[1] MAX \" ";
$def[1] .= "GPRINT:var1:AVERAGE:\"%3.4lg %s$UNIT[1] AVERAGE \" ";
?>
</code>

Note: as the number (1) and the letter "L" look alike in this listing: the format "%3.4lg" contains a small letter.

**''$opt[1] = "--title ...''** sets RRDtool options for the first set of data, here the title as you can see. Embedded quotes are masked using a backslash (\). The variables ''$hostname'' and ''$servicedesc'' were determined through the call of PNP and are available for the template as well.

**''$def[1] =  "DEF:var1=$rrdfile:$DS[1]:AVERAGE ";''** defines which data is to be read from which RRD file. $rrdfile contains the path to the RRD file of this service. $DS[1] refers to the first data series from the RRD file.

**''$def[1] .= "AREA:var1#00FF00:\"Response Times \" ";''** the operator ".=" appends more data to the array $def[1]. An area will be drawn using data from the variable ''var1''. The color is defined in HEX notation #00FF00 (red, green, blue). The label is "Response Times".

**''$def[1] .= "LINE1:var1#000000 ";''** As completion of the just drawn area a line (LINE1) will be drawn in black (#000000).

**''$def[1] .= "GPRINT:var1:LAST:\"%3.4lg %s$UNIT[1] LAST \" "; \\
$def[1] .= "GPRINT:var1:MAX:\"%3.4lg %s$UNIT[1] MAX \" "; \\
$def[1] .= "GPRINT:var1:AVERAGE:\"%3.4lg %s$UNIT[1] AVERAGE \" ";''**

The three GPRINT lines build up the caption for the graph. The current values are formatted using the [[wp>printf]] syntax.


===== Available variables =====

Using the data collector ''process_perfdata.pl'' PNP stores not only performance data but other values exported by Nagios. These values are stored in the XML file associated to the appropriate service.

In the first part of the XML file the performance data is stored in separate components.

<code xml>
<NAGIOS>
  <DATASOURCE>
    <TEMPLATE>check_http</TEMPLATE>
    <DS>1</DS>
    <NAME>time</NAME>
    <UNIT>s</UNIT>
    <ACT>0.006721</ACT>
    <WARN>1.000000</WARN>
    <CRIT>2.000000</CRIT>
    <MIN>0.000000</MIN>
    <MAX></MAX>
  </DATASOURCE>
....
</NAGIOS>
</code>

The field <DS> designates the data source and is used to identify the data series of the RRD files and is the key of the following arrays as well.

The array ''$UNIT[1]'' contains the unit of measurement of the first data series.

The XML file contains other information. When process_perfdata.pl is used in default mode all available macros are at hand with the current values. For the benefit of readability the following lines show only an extract. 

<code xml>
<NAGIOS>
...
  <NAGIOS_SERVICENOTIFICATIONID>8418</NAGIOS_SERVICENOTIFICATIONID>
  <NAGIOS_SERVICENOTIFICATIONNUMBER>0</NAGIOS_SERVICENOTIFICATIONNUMBER>
  <NAGIOS_SERVICEOUTPUT>HTTP OK HTTP/1.1 200 OK - 10087 bytes in 0.125 seconds</NAGIOS_SERVICEOUTPUT>
  <NAGIOS_SERVICEPERCENTCHANGE>0.00</NAGIOS_SERVICEPERCENTCHANGE>
  <NAGIOS_SERVICEPERFDATA>time=0.124811s;;;0.000000 size=10087B;;;0</NAGIOS_SERVICEPERFDATA>
  <NAGIOS_SERVICEPERFDATAFILE></NAGIOS_SERVICEPERFDATAFILE>
  <NAGIOS_SERVICEPROBLEMID>0</NAGIOS_SERVICEPROBLEMID>
  <NAGIOS_SERVICESTATE>OK</NAGIOS_SERVICESTATE>
  <NAGIOS_SERVICESTATEID>0</NAGIOS_SERVICESTATEID>
  <NAGIOS_SERVICESTATETYPE>HARD</NAGIOS_SERVICESTATETYPE>
  <NAGIOS_SHORTDATETIME>27-12-2007 13:51:23</NAGIOS_SHORTDATETIME>
...
</NAGIOS>
</code>

The various XML fields can be used as variables in the PNP templates. Each field is available as a variable with the same name.

The value of the field ''<NAGIOS_SERVICEOUTPUT>'' is available as the variable ''$NAGIOS_SERVICEOUTPUT''