1. Home
  2. Documentation
  3. Advanced
  4. SLA Reporting

SLA Reporting

Installation

This plugin is marked as optional/recommends due to depedencies to xlibs, xvfb and fonts.

To install use the package 'thruk-plugin-reporting' from Consol Labs Repository.

How it works

SLA Reporting consists of several steps.

  • report configuration

  • report template

  • converting html report into pdf

  • optionally send report by mail

Report Configuration

You can create and adjust report settings on the 'Reporting' page. Make sure the plugin is enabled. After selecting a template for your report you have to set specific types of input fields on the second page. If you make you report public, everyone can view and refresh the report.

Report Templates

All templates used for reports can be found in 'plugins/plugins-enabled/reports2/templates/reports'. You may adjust or override all templates to your needs and put them into a 'reports' subfolder of the 'user_template_path'.

  | reports     contains the selectable reports
  |- comp       contains components used in reports
  |- locale     contains localization settings
  |- style      contains css used to make reports pretty

See link:../api/Thruk/Utils/Reports/Render.html for details on available functions and examples.

The Templates itself are written in Template::Toolkit which is perfectly documented at http://template-toolkit.org/docs/manual/index.html

Converting

The generated HTML report will be converted into a pdf file using puppeteer.

Sending Reports By Mail

It’s quite easy to setup sla reports by mail. All you need is to create send option in the report configuration. It is even possible to send one report at multiple times.

Debugging Reports

Sometimes it may be necessary to create a report in debug mode in order to save information to reproduce the report for developers.

In order to create debug information for a report, open the reports page and add the debug parameter. The url should end with reports2.cgi?debug=1. You may have to remove the # sign and everything after it.

  • Append ?debug=1 to the url. This will show an additional icon next to each report.

  • Click on the wizards wand icon next to the refresh button

  • Download the debug information with the icon next to the wizards wand.

Customized Reports

Reports can be customized with some HTML and CSS knowledge. Reports in general have several blocks which specify the steps done to produce the report.

  • styles

  • edit

  • prepare

  • render

  • mail

Styles

Customizing css styles of your reports is easy. You need to create a new file 'reports/style/custom.tt' below your 'user_template_path'.

For example:

<style type="text/css">
/* override css styles */
BODY {
    /* use a different font */
    font-family: arial, sans-serif;

    /* change default font color */
    color: DarkSlateGray;
}
TD.header DIV.title {
    /* change gradient on page cover and page header */
    background: linear-gradient(to bottom, #d0e4f7 0%,#73b1e7 24%,#0a77d5 50%,#539fe1 79%,#87bcea 100%);
}
</style>

<script language="javascript" type="text/javascript">
  /* add complete new elements by javascript, ex.: company logo on page cover */
  jQuery(document).ready(function() {
    jQuery('<img src="http://www.thruk.org/images/logo_thruk.png">').insertBefore('DIV.page.cover DIV.titletext');

    // note: the image must be accesible from the monitoring host, sometimes its easier to use embedded base64 encoded images:
    //jQuery('<img src="data:image/png;base64,...">').insertBefore('DIV.page.cover DIV.titletext');
  });
</script>

If thats not enough, you still can change each and every template used to create the reports.

Edit Block

The edit block contains configuration items used for this report. They create the edit page when someone chooses to create or edit a report of this type. Basically this block contains all required and optional fields used for this report.

For example:

[% IF block == 'edit' %]
  [%
    required_fields = [
        { 'host'       => [ 'Host',        'hosts',         ''              , '', 1 ] },
        { 'timeperiod' => [ 'Timeperiod',  'rptimeperiod',  'last12months'          ] },
    ];
  %]
[% END %]

The key in that hash defines the parameter by which that value can be accessed later. Each field has to point to an array with at least 3 values. The required flag is optional.

  • Name

  • Type

  • Default value

  • Required Flag

Prepare Block

The prepare block is used to gather data used in the report. Usually it’s been used to get availability data via livestatus or fetch events from logfiles.

For example:

[% IF block == 'prepare' %]
  [%
    set_unavailable_states(param.unavailable);
    calculate_availability();
  %]
[% END %]

You may use all functions available from the Render Helper

Render Block

The render block defines the layout of the report.

For example:

[% IF block == 'render' %]
  [% PROCESS 'reports/locale/en.tt' %]
  [%
    title        = 'Hello World Report'
    subtitle     = r.name
    coverdetails = [ 'Report Timeperiod:', get_report_timeperiod(start, end, reportDateFormat),
                     'Host:', param.host,
                   ]
  %]

  [% WRAPPER 'reports/comp/report.tt' %]
    [% WRAPPER 'reports/comp/page_cover.tt' %][% END %]
    [% WRAPPER 'reports/comp/page_standard.tt' %]
      <b>hello world</b>
    [% END %]
  [% END %]
[% END %]

This report would contain 2 pages. First you wrap everything into the report.tt which defines the basic report layout and contains the stylesheets. Then you have to define some settings used by the cover page. 'r' is a reference to the report object, in this example we just use that as subtitle. 'coverdetails' is a list of name / value pairs used in the details list on the cover page. Finally we wrap a 'hello world' in a standard page. The content could contain standard HTML tags like tables and images as well.

Mail Block

Finally we define a mail block which is used for the mail layout if a report is sent by e-mail.

For example:

[% IF block == 'mail' +%]
SUBJECT: Report: [% r.name %]

Your report is attached.

[% IF r.desc %]Description: [%+ r.desc %][% END %]
[%+ END %]

We use the report name 'r.name' as subject and put the report description 'r.desc' in the body.

Custom Perl Render Helper

You may create a Perl Module named 'Thruk::Utils::Reports::CustomRender' which will be automatically made available to the stash, so functions from this module can be used in the reporting templates.

Edit page on GitHub