User Guide

Service Management - Incident Response

How to Create a Report for a Hostgroup

This How To will help you define and produce a basic report for a Linux hostgroup. It assumes you already have a set of Linux systems being monitored which are configured as a single hostgroup.

Start the Reporting module and select the Open reports action, which will display the list of existing reports in the Reports tab.

Before you can define a report, you must first make sure that the Time Frame you want already exists. If you cannot find one among the defaults, you will need to switch to the Time Frames tab to create one.

A time frame consists of a descriptive name to distinguish it from other time frames, a start date/time, and an end date/time. These dates/times can be either absolute by choosing it with the date picker widget, or relative expressed as a text string. You can find more information in the documentation of Supported PHP Time Formats.

Examples include:

  • now (only as an end date/time)

  • -4 hours

  • -1 year*

  • monday last week midnight

  • first day of January this year midnight

When done, click on the Create Time Frame button.

You can now return to the Reports tab and select the New Report action to create a new report definition.

In the form, fill in the fields for Name, Time Frame and Report. The Report field corresponds to the type of report to create:

  • Host SLA: A report based on whether a host or hostgroup meets an SLA threshold.

  • Service SLA: A report based on whether a service or servicegroup meets an SLA threshold.

  • System: A phpinfo report that displays PHP and server settings.

You can produce a Host or Service SLA report with just the information for these three fields and the remaining defaults, although this will include all hosts or all services in your report. To select a subset of hosts or services, add a filtering expression using the monitoring reference guide.

Since this How To is to create a Linux Hostgroup report, select the Host SLA report type and fill in the monitoring expression for your group, e.g.: hostgroup_name=LinuxServers. Then select a Breakdown like “Day” and a Threshold like “99.5”. Click on the Create Report button to define the report with the chosen parameters and add it to the list.

Click on your newly created report to see the current SLA for each host in your hostgroup, modify your report parameters, or schedule the report to be run at regular intervals.

How to Calculate Availability using the SLM Module

In this how-to, you will learn how to set up an availability report using SLA types in the Service Level Management (SLM) module. A Service Level Agreement (SLA) is a contract between your company and a customer. If you offer similar SLAs to multiple customers, the standard elements of the agreement should be separated from the customers’ data: the SLM module makes this separation explicit during the configuration phase.

The following scenario will be used as guidance throughout the howto. Suppose you need to monitor for your company (called ACME) the availability of services on three hosts of your network (acme_linux_01,acme_linux_02, and acme_windows_01) and make sure that those services are available 99.9% of the time during working hours (9AM to 5PM, or 9:00-17:00), measured weekly.

There are three elements in the SLM module that you need to configure:

  • SLA Type: Basic SLA information that can be reused across many customers

  • Customer: A table of customers and of their data

  • Contract: The pairing of a customer and an SLA type for a specific set of monitored objects

In a nutshell. In order to create a SLA, the first step is to define the Time Period needed in the Director, then use that Time Period to set up one type of SLA Type, add customers data, and finally define the Contract.

Step #1: Configure a Time Period

Follow the menu Icinga Director > Timeperiods > Timeperiods and click on Add. Since the scenario defined above say the requires availability during working hours, create one Time Period and call it Working Hours (use the same for the Display Name field).

In this howto, the other fields will not be covered, so go ahead and click on Add at the bottom of the form.

Now move to the Ranges tab and add the five days of the week and hours for each like this:

Day(s)

Timeperiods

monday

09:00-17:00

tuesday

09:00-17:00

wednesday

09:00-17:00

thursday

09:00-17:00

friday

09:00-17:00

When done, you will need to deploy the new time period in Director (Icinga Director > Activity log > Deploy pending changes).

Step #2: Configure an SLA Type

You can now go to the SLM module. After clicking on the SLM menu entry you should see a list of any SLA types you have already defined. Let’s create a new SLA type that fulfils the required criteria by clicking on Add. Enter a name, such as Working Hours by Week, and a description.

Next, select the time period defined in Step #1 from the Time Period drop-down. Then select Weekly from the Calculation Period drop-down, since the availability is measured per week, Finally, enter the target availability (99.9% in our case) and click on the Store button. You’ve now created an SLA type that you can later reuse across multiple customers.

Step #3: Add a Customer

Next you need to create a Customer. Switch to the Customers tab, where you will see a list of existing customers. Let’s add a new one, say Acme, S.p.A., along with a short description.

That’s it for this tab! Store the data and let’s go to the next step.

Step #4: Add a Contract

Now you need to link an SLA type to the customer and specify which hosts and services are covered in the SLA.

Go to the Contracts tab and click on the Add action. Enter a name like Acme Weekly Availability and a description. From the Customer drop-down, choose the Acme, S.p.A. customer and then from the SLA Type drop-down choose Working Hours by Week, as defined in Step #2.

All that’s left for configuration is to define the set of monitored objects. These are specified by using a filtering expression. In our scenario, you can use the following filtering expression, as long as no other host names begin with the string “acme”:

host_name=acme*

When done, click on the Store button to save the configuration.

Step #5: Create the Availability Report

You are almost done: Once the SLA contract is set up, you can create and print an availability report on demand. Follow the instructions to create a report, making sure to set the report type to SLM Report and the customer to Acme, S.p.A..

The monitoring data needed to detail availability will be automatically calculated and then imported for all SLA contracts defined in Step #4 for that customer.

How to Show the Availability of a Business Process

A typical scenario for availability reporting is to show the logical availability of all the monitored objects (e.g., hosts and services) defined by an explicit Business Process model. So for instance if you have two redundant core network switches sized for failover, you can model them with a logical OR and report their joint availability rather than reporting on them separately.

In this How To you will create a sample business process, set up some report parameters, and generate a report covering the services that are part of that business process.

Prerequisites

  • The Business Process module must be enabled (Configuration > Modules > businessprocess > enabled)

  • The SLM module must be installed under User Guide ‣ Initial Configuration ‣ Installing Additional Modules (see Installing Additional Modules)

Step #1: Set up a Business Process (or Reuse an Existing One)

First, let’s configure a business process to use as an example for checking availability. Open Business Process from the left side menu and select Create. In the panel that appears, enter the following information:

  • Name: Company.com

  • Title: ERP Services

  • Description: The services that compose ERP for Company.com

  • Backend: Keep the default backend

  • State Type: Keep ‘Use SOFT states’

  • Add to menu: Change this to ‘No’

Next, create three child nodes for our new business process with the following structure:

  • ERP System

  • Inventory Server (Host)

  • Supply Chain Server (Host)

If you’ve never created a business process node before, you can follow the official Icinga tutorial.

Step #2: Configure Checks in Director

Next, go to the Icinga Director module and set up the following:

  • If it doesn’t already exist, create and deploy a new host template of type generic-host.

  • Create a host inheriting from that template named business-process-checker, with the Host address set to 127.0.0.1 (if using a cluster, set it to the public facing cluster IP).

  • Open Icinga Director > Commands > External Commands* and search for icingacli-businessprocess-neteye. In its Fields tab, make sure the Business Process Process ID field is set to mandatory.

  • If it doesn’t already exist, create and deploy a new top-level service template named business-process-service-check, setting its check command to icingacli-businessprocess-neteye.

  • Create a service named business-process-check* on that service template and link it to your previously created **business-process-checker host, specifying the top-level business process node *ERP System (from Step #1) in the field Business Process Process ID.

  • Deploy the Director configuration (Icinga Director > Activity Log > Deploy)

  • Go to Overview > Hosts, and check that both the business-process-checker host and its service are up and running.

Step #3: Configure Time Periods in Director

In the Director module, define the Timeperiod during which our business process is contractually required to be up and running. In this example, it will be the entire week excluding Saturday and Sunday.

  • Go to Icinga Director > Timeperiods > Timeperiods

  • Create a new Timeperiod called “24x5”

  • On the Ranges tab, set the time ranges as follows (Director will sort them alphabetically):

    friday:      00:00-24:00
monday:      00:00-24:00
thursday:    00:00-24:00
tuesday:     00:00-24:00
wednesday:   00:00-24:00

  • Then deploy the Director configuration (Icinga Director > Activity Log > Deploy) so that the time ranges can be used in the next step.

Step #4: Set up Service Level Management

Now you can set up the processing step that will link the underlying BP service availability data to the reporting parameters. This step is carried out in the SLM module:

  • In the Customers tab, add a customer such as “Company.com”

  • In the SLA Types tab, create a new instance with the following parameters:

    • Name: Gold

    • Operational Time: 24x5 (the value from the previous step)

    • Calculation Period: Daily

    • Availability: 99.5

    • Downtime: (not checked)

  • In the Contracts tab, add a new contract with:

    • Name: Company 24x5 BP Availability

    • Description: (same as above)

    • Customer: Company.com

    • SLA Type: Gold

    • Objects Filter: “service_description=business-process-check” (you could also run this as a single top-level host/service check by using “host_name=business-process-checker”)

Once you add an objects filter, you will immediately see links to the hosts and services it maps to, allowing you to double check that those you expected are there. Please ensure that at least one host or service is returned.

Step #5: Create the Report

Finally, let’s define the report elements for the business process.

After naming the report, you will need a Time Frame that specifies the starting and ending dates/times for the report. If none of the existing Time Frames fit your needs, go to the Time Frames panel, and add a new one by selecting the “New Timeframe” action. Enter the following parameters (remember that the calculation period must be shorter than the time frame):

  • Name: “Last week including today”

  • Start: “last week”

  • End: “tomorrow”

Next, define a new report by specifying the type and any parameters necessary for that type:

  • Name: Business Process Report

  • Timeframe:* Last week including today

  • Report: SLM Report

  • Customer: Company.com

You can now view the new report by clicking on its name in the table. You should see the availability of the Business Process host business-process-checker and its associated service business-process-check that you configured in Step 2 above.

How to Export SLM Data to a CSV File

You may want to integrate report data into your existing reporting or data warehousing solutions. You can export this data in CSV format, which is a standard machine readable format handled by all common data processing and business intelligence apps. This allows you to further process report data tailored to your business, for instance by adding statistics or graphics, or correlating it with other data sources.

This How To you will show you the procedure for exporting SLM data from an existing report to a CSV (comma separated values) file.

Prerequisites

  • The SLM module must be installed under User Guide -> -Initial Configuration ‣ Installing Additional Modules (see Installing Additional Modules)

  • The SLM Report you want to export must already be defined in the Reporting module

The Export Script

The script export_csv_report.php can be used to export SLM report data from a shell. Its required parameters are:

-u

User name (any valid Icinga user)

-p

Password

-i

The Report ID (see below)

-f

A valid path ending in a filename. If the path does not exist, an error will be returned. If the script runs successfully, the file will contain the report data in CSV format.

You can get further information about its other available parameters as follows:

# php /usr/share/neteye/reporting/scripts/export_csv_report.php --help

To obtain the report ID, navigate within the NetEye interface until you arrive at the desired report. It should have a URL similar to the one here (use the number at the end of the URL as the value for the -i parameter):

https://<host>/neteye/reporting/reports#!/neteye/reporting/report?id=16

Once you have all the required information, you can call the export script as in this example:

# cd /usr/share/neteye/reporting/scripts/
# php ./export_csv_report.php -u root -p pass -i 16 -f /home/my-report.csv

And finally, the resulting exported file should look like this:

# cat /home/my-report.csv
Contract,"Object Type","Object Name",Timeperiod,Availability
"Contract A",Hosts,webserver,2019/08/26,100.00%
"Contract B",Hosts,email-server,2019/08/26,99.70%
"Contract C",Services,disk-check,2019/08/26,98.30%

How To Create a Customised Theme For SLM Availability Reports

The HTML version of customer’s Availability Reports can be modified on a per-customer basis, allowing therefore to provide reports with a unique, tailored layout to each customer.

This feature works currently only from the command line; hence a basic degree of knowledge and acquaintance with the Linux command line and with HTML and CSS is required in order to successfully complete this howto.

Custom reports are built using the Handlebars templating engine; hence all necessary file that you would use need to have the .hbs extension (like e.g., custom_logo.hbs). You can find some basic notions of Handlebar’s syntax and capabilities in the official language guide.

First of all, we mention some important directory that will be used next:

  • Default templates can be found and reused from /usr/share/slmd/templates/

  • Customised templates are stored in a directory under /neteye/shared/slmd/conf/custom_templates/

Scenario

We want to customise a theme for SLM Availability Report for customer ACME, Inc., which conforms to their corporate identity, by adding (1) their logo and (2) the font they use in all its reports, that is, for the daily, weekly, and monthly reports.

Step #1: Copy the necessary files

The first step is to create a new directory in which to store the customised files. We’ll call it simply acme:

[root@neteye-413 ~]# mkdir -p /neteye/shared/slmd/conf/custom_templates/acme/partials
[root@neteye-413 ~]# ls -l /neteye/shared/slmd/conf/custom_templates/acme/
total 0
drwxr-xr-x. 2 root root 6 Jun 17 15:16 partials

Next, we need to copy there all the necessary files; we mentioned that default templates are in /usr/share/slmd/templates. Under that directory, you find the following files:

daily_report_template.hbs
weekly_report_template.hbs
monthly_report_template.hbs
--partials (directory)
    -- outages_report.hbs
    -- report_footer.hbs
    -- report_header.hbs
    -- report_legend.hbs

Files right under the templates directory define the structure of the build daily, weekly, and monthly reports and pull the content from SLM data, while files under the templates/partials directory contain only part of the reports and might be included or not in the above-mentioned three reports.

Since we want to customise the logo in the header, we copy only partials/report_header.hbs:

[root@neteye-413 ~]# cp /usr/share/slmd/templates/partials/report_header.hbs /neteye/shared/slmd/conf/custom_templates/acme/partials

In order to customise a whole report, you should copy also the appropriate daily, weekly, or monthly template under the acme directory you just created, for example, to modify only the daily template, copy the daily_report_template.hbs:

[root@neteye-413 ~]# cp /usr/share/slmd/templates/daily_report_template.hbs /neteye/shared/slmd/conf/custom_templates/acme/

If you do not copy any of the daily, weekly, or monthly report, the report_header.hbs file will be used for all templates, which is indeed what is required in our sample scenario.

Note

The acme template will now be shown in the drop-down menu called Report Template that appears when you add a new customer under SLM > Customers.

Step #3: Customise the CSS

Since ACME corporate identity uses a given font, Lato, we want its template to mimic it; therefore we need to change the reports’ style to use that font by default.

Remaining under the partials directory, we create a new file acmestyle.hbs with the following content:

<style>
body {
    font-family:"Lato","Helvetica New",Arial,sans-serif;
}
</style>

As you can see from this snippet, only inline CSS is supported in templates. As the last task, we need to tell the header to use the the custom CSS. Similar to what we did in the previous step for the logo, we need to make sure that the template includes this file:

<!-- Partial - SLM Report Header -->
{{~> partials/acmestyle ~}}
<!-- SLM Report Name -->
<section class="section section--evencolumns">
{{~> partials/custom_logo ~}}
    <div class="wpcol wpcol--2of3">
    <h1 class="title title--large">{{report_data.report_name}}</h1>
    </div>
</section>

You can now use your fully customised template for ACME, Inc.’s report templates: edit the ACME, Inc. customer under SLM > Customers and assign to it the acme template.

Conclusions

We have shown how to modify a few characteristics of a report template, but many more possibilities exists: you can completely revamp the layout of the templates by adding a completely customised CSS; you can add a background image to the report, modify the fonts used for every component of the HTML report (div, span, h2 etc).

When dealing with Handlebars, like for any other templating engine, it is nonetheless important to focus on two points:

  • There is no check on the syntax of the file(s) you include, so make sure that the elements you include are valid (like, e.g., CSS and HTML structure and syntax, correctly encoded images, and so on)

  • In the template, all the strings that need to pull data and content from the SLM backend must be enclosed in double curly braces (like, e.g., {{month_day_number}} or {{translate "report.common.week_days.short.mon"}}