PDF Reports

Xymon PDF reports gathers a bunch of scripts mainly written in PHP and shell. The main objective of these scripts is to dynamically generate PDF reports of your servers from a web page. You will have two web pages to obtain your reports.

The first page, called pdf.php, is for the simple reports. On this you will have only 4 or 6 graphs and that's all. It's simple and clear. In addition, you have an availability pie chart !

The second page called analysis.php, is a bit more complex but, this time, you can write something below the graphes. With a little javascript you even can fill automatically the reports.

* Grab a copy of 'tcpdf' from http://www.tcpdf.org/ . At the time of writing, last version is 4.3.006.

* Unzip it somewhere ! Give your Webserver the authorization to access it.

# chown -R www-data:www-data /path/to/tcpdf/

* Then un-gzip the 'xymon_pdf.tar.gz' archive in a directory of your choice ($BBHOME/server/www/pdf for example).

* Give your Webserver the authorization to access it. You must also authorize everyone to write into 'graphrrd'.

# chown -R www-data:www-data $BBHOME/server/www/pdf
# chmod -R 777 $BBHOME/server/www/pdf/graphrrd

* Edit the 'include/config.inc.php' to match your configuration. You nearly have nothing to change, just two paths !

* Edit 'class.report.inc.php' and/or 'class.analysis.inc.php' to change the logo appearing on top left of reports and text for footers/headers.

* Edit '$BBHOME/server/www/menu/menu_items.js' and add two lines in 'Reports' section like those ones (I put my scripts into $BBHOME/server/www/pdf) :

['Analysis PDF', '/xymon/pdf/analysis.php'],
['Reports PDF', '/xymon/pdf/pdf.php']

* Open a browser and go to 'pdf.php' or 'analysis.php' and then try to generate a report… You will only see the document structure :(

* Now, you have to generate some images to include into reports. To do so, I wrote several shell scripts to generate them. All you have to do is to configure the 'scripts/config' to match your setup and launch 'master.sh' from a command line.

* If this works, you can use a 'crontab' to periodically generate these graphs.

# m h  dom mon dow   command
*/30    *       * * *   cd /path/to/pdf/scripts/; ./master.sh

* Basically, you will only see FOUR graphes on the reports. I found that the Run-Queue Length and I/O wait rate are good indicators to detect a trouble on my systems. You can have these information with 'SAR'. It works on every Unix flavour and is more accurate than 'vmstat'. If you don't want to use 'sar', it will work but with only four graphes.

* I choose to include 6 graphes in the reports generated from 6 rrd (I will add more in the future). For me, these graphes are the most significant to understand if the server is in good health or not.

# cpu : CPU utilization (la.rrd)
# memory : Memory and Swap utilization (memory.*.rrd)
# net : Network Traffic (netstat.rrd or ifstat.rrd)
# iowait : I/O wait rate (?)
# runqueue : 'Real' CPU load (?)
# vmstat : CPU 'Utilization' (vmstat.rrd)

* If you want to use 'sar', copy the 'bb-sar.sh' script from this archive in 'scripts/ext/' or download and install the 'bb-sar-0.9.tar.gz' script from deadcat.net (http://www.deadcat.net/viewfile.php?fileid=686) and install it to your Xymon clients 'ext/' directory.

* Edit 'clientlaunch.cfg' from your client 'etc/' directory and add the following lines. You must have a new test on your hobbit display called 'sar' with a lot of tests within.

[sar]
        ENVFILE $HOBBITCLIENTHOME/etc/hobbitclient.cfg
        CMD $HOBBITCLIENTHOME/ext/bb-sar.sh
        LOGFILE $HOBBITCLIENTHOME/logs/bb-sar.log
        INTERVAL 5mde Text

* Copy the script 'extragraph.sh' from 'scripts/ext/' to your Xymon server 'ext/' directory. This script has been successfully tested for Aix 4.2→5.3, HP-UX 10.20→11.23, Redhat AS Linux 2.1→4 and Solaris 6→10.

* Watch out for the locale used on your system !! All my systems are configured with english locale and so are my scripts. If something is not working, please check the output of a 'sar' command ('sar -A 1 1') and seek for the word 'Average'. This word is used in my 'extragraph.sh' script to extract the infos…

* Edit $BBHOME/server/etc/hobbitlaunch.cfg and add “–extra-script=$BBHOME/server/ext/extragraph.sh –extra-tests=sar” to the 'rrdstatus' and 'rrddata' definition. You should have :

[rrdstatus]
        ENVFILE /Soft/hobbit/server/etc/hobbitserver.cfg
        NEEDS hobbitd
        CMD hobbitd_channel --channel=status --log=$BBSERVERLOGS/rrd-status.log hobbitd_rrd --rrddir=$BBVAR/rrd **--extra-script=$BBHOME/server/ext/extragraph.sh --extra-tests=sar**

[rrddata]
        ENVFILE /Soft/hobbit/server/etc/hobbitserver.cfg
        NEEDS hobbitd
        CMD hobbitd_channel --channel=data --log=$BBSERVERLOGS/rrd-data.log hobbitd_rrd --rrddir=$BBVAR/rrd **--extra-script=$BBHOME/server/ext/extragraph.sh --extra-tests=sar**

* If you want graph in trends and sar test, add “,sar” to GRAPHS and TEST2RRD definitions in '$BBHOME/server/etc/hobbitserver.cfg'.

* Finally, you must add the correct graph definition in '$BBHOME/server/etc/hobbitgraph.cfg' :

[sar]
        TITLE Sar I/O
        YAXIS %CPU
        DEF:wio=sar.rrd:sar_wio:AVERAGE
        DEF:rq=sar.rrd:sar_rq:AVERAGE
        LINE2:wio#FF0000:I/O wait
        COMMENT: %CPU
        GPRINT:wio:LAST:cur \:%3.2lf
        GPRINT:wio:MIN:min  \:%3.2lf
        GPRINT:wio:AVERAGE:avg \:%3.2lf
        GPRINT:wio:MAX:max \:%3.2lf \n
        LINE2:rq#0000CC:Run-queue
        GPRINT:rq:LAST:cur \:%3.2lf
        GPRINT:rq:MIN:min  \:%3.2lf
        GPRINT:rq:AVERAGE:avg \:%3.2lf
        GPRINT:rq:MAX:max \:%3.2lf \n

* In a few minutes you should see a graph in 'trends' and 'sar' test. That's good ! If you don't see any graphs, something goes wrong :( Feel free to contact me in case of troubles…

* You should try again to launch 'master.sh' and generate a pdf report. This time it will show you 6 graphes !

Simply download and you'll get it !

* Troubles seem to occur with TCPDF and alpha-transparency in PNGs.

* Design/Look'n'feel considerations.

• 2008-11-21
  • Release 1.2b

• 2008-11-26
  • Release 1.2c

• 2008-12-02
  • Release 1.2h