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 that for your company (called ACME) you need to monitor 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) from Monday to Friday, 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 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 under Configuration / Modules / businessprocess
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 Time Period 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:

.. code:: bash

# 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:

.. code:: bash

# 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:

.. code:: bash

# mkdir -p /neteye/shared/slmd/conf/custom_templates/acme/partials # 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:

├── partials
│   ├── report_legend.hbs
│   ├── report_header.hbs
│   ├── report_footer.hbs
│   └── outages_report.hbs
├── weekly_report_template.hbs
├── monthly_report_template.hbs
└── daily_report_template.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:

.. code:: bash

# 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:

.. code:: bash

# 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 #2: Add the logo¶

The logo needs to be encoded in base64; under Linux you can simply use the application with the application of the same name (there exist online converters as well):

.. code:: bash

# base64 logo.png > /neteye/shared/slmd/conf/custom_templates/acme/partials/acme_logo.hbs

We pipe the output to a file, so it is immediately available for inclusion in the templates.

By using the {{~> partials/acme_logo ~}} syntax, indeed, Handlebars will look for a file called acme_logo and replace that whole string with the verbatim content of the file, in this case the acme_logo.hbs file saved in the partials directory.

You can then edit the file report_header.hbs and add the string {{~> partials/acme_logo ~}} in the most appropriate place of the template, making sure to omit the suffix:

<!-- Partial - SLM Report Header -->

<!-- SLM Report Name -->
<section class="section section--evencolumns">
    <img src="data:image/png;base64,{{~> partials/logo~}}" />
    <div class="wpcol wpcol--2of3">
    <h1 class="title title--large">{{report_data.report_name}}</h1>
    </div>
</section>

Note that the path is always relative to the base directory, which in this case is /neteye/shared/slmd/conf/custom_templates/acme.

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"}}