Configuration¶

SLA Reports¶

The SLM module is compatible with Icinga’s Reporting module. One use of the data provided via SLM is for creating availability reports for the monitored objects included in each customer contract.

To create an availability report, you will need to:

Configure one or more customers, SLA types, and contracts in the SLM module
Create a new report in the Reporting module and set the following fields, which are all compulsory:
- Name: A name that uniquely identifies the report
- Timeframe: Selecting a value here defines for how much time the report will be generated. This value must be higher than the calculation period defined in the SLA Type for which the report is generated, otherwise it will lead to an empty report (see next section).
- Report: Set this to SLM Report, whereupon the form will add the following field
- Customers: Choose the customer you want to create the report for
- Contract: Choose the contract corresponding to the data to be processed in the report. In the Contract dropdown, you will be able to select only those contracts where the Calculation Period is defined to be smaller than the selected Timeframe. This ensures that the report will have an appropriate number of pages.
- Consider Event Adjustments: With this drop-down, users with the appropriate permission can choose whether or not to consider user-defined event adjustments in this report. There are three possible choices:
  - <Yes/No> (inherited from “< ContractName >”): This option contains the Consider Event Adjustment flag value (i.e. Yes or No) with the contract name from which the value is inherited.
  - Yes: Override that value, forcing event adjustments to be considered
  - No: Override that value, forcing event adjustments to be ignored
- Include Average Availability: With this drop-down, users can choose whether or not to include average availability in this report. There are three possible choices:
  - <Yes/No> (inherited from “< ContractName >”): This option contains the Include Average Availability flag value (i.e. Yes or No) with the contract name from which the value is inherited.
  - Yes: Override that value, forcing average availability to be included
  - No: Override that value, forcing average availability to be ignored
- Show Outages Count: Show how many Outages are defined per calculation period.
- Show Outages List: Show Outages in the report. If set to Yes the following fields will appear:
  - Show Outages List Limit: Set the maximum number of outages to show per calculation period.
  - Sort Outages by: Users can sort Outages by Duration or by Start/End Date. If not specified, Outages are sorted by Duration.
  - Outages order: Users can invert the Outages sorting order by selecting the Ascending or Descending option in this field. Descending is the default order.

After you click on “Create Report”, the report will appear in the list of available reports.

Within each report, you can read the details related to the selected contract and its monitored objects. This information is typically divided into hosts and services, and represents their percentage of availability. The availability of a monitored object will be green if it is above the threshold defined in its SLA Type, and red if not. In addition, all monitored objects that did not record any events during the reporting period will be listed separately.

You should ensure that the filter expression used in the Objects Filter field on the Contract tab returns at least one monitored object (e.g., at least one host or service).

Invalid Report Configurations¶

While the SLM module does not allow users to create incorrect report configurations, there are circumstances in which reports may seemingly contain wrong data, namely when the report is empty or very large. The reasons behind these two cases, along with solutions, are explained in the next sections.

Configurations Leading to Empty Reports¶

If the report’s time frame and the contract’s calculation period aren’t compatible, the report generated will be empty. This can happen when:

The Calculation Period is greater than the Time Frame. For example, setting the calculation period to monthly_12 and defining the time frame to be from 01.01.2019 to 01.06.2019. This would be like trying to fit 12 months inside 6 months.
The time frame doesn’t contain at least one entire and valid calculation period. For instance, when you define a report with a monthly calculation period, while the time frame is defined to start on 02.07.2019 and finish on 29.08.2019. Here, neither the time within July nor the time within August represents a complete month.

If you find you have created a report definition matching one of these cases, you can fix it with one of the following solutions:

Make the time frame defined for the specific report longer
Select a different SLA Type in the contract form, with a smaller calculation period
Select a smaller calculation period in the definition of the SLA type associated with the contract used for creating the report

Configurations Leading to Very Large Reports¶

If the combination of a report’s time frame and the contract’s calculation period would lead to a number of calculation period slots higher than a pre-determined limit, it strongly implies that the report produced would have an excessive number of pages.

NetEye attempts to avoid this situation by preventing a user from creating very large reports. In general, reports consisting of hundreds of pages are not useful. However, should you wish to override this upper bound for the allowed number of calculation periods, you can change this limit in the SLM module’s configuration page (Configuration / Modules / slm / Configuration) with the field Maximum report size. If you do so, please note that increasing this limit will lead to a proportional decrease in performance.

Event Adjustments¶

The Event Adjustment Web Interface¶

Whether event adjustments will be considered or not during report generation can be set with the flag “Consider Event Adjustments” on the associated SLA Contract. This will be taken as the default behavior for any reports produced for that contract. The value selected for this flag may be overridden in the Reporting module by users who are granted the permissions described below.

Viewing Permissions

By default, only users with the admins role can access the SLM module. Non-admin users who need to view an SLM report will need special permissions to access or modify this flag or the other items (i.e., Contracts, customers, and SLA Types) in the SLM Module. To grant these permissions to users, you need to create a role (go under Configuration / Authentication / Roles) with a suitable permission (like e.g., report-adjustment-override or admin) over the SLM module. Enabling only General Module Access permission will give only View Access to slm Event Adjustment.

To set these permission for a non-admin user requires first to enable the General Module Access permission for the SLM module.

Creating an Event Adjustment¶

To add a new event adjustment, go to SLM / Event Adjustments and enter values for the following options:

Object Type: Type of the monitoring object, can be host or service.

Host Name: Name of the host to which to attach the event.

Service Description: Name of the service, running on host passed in the Host Name field, to which to attach the event

Description: Title for the event

Start: Timestamp for the starting point of the event (YYYY-MM-DD hh:mm:ss)

End: Timestamp for the ending point of the event (YYYY-MM-DD hh:mm:ss)

Event Type: State for the event; The event type must be one of the values in Table 15 that are available for the monitored object passed in the Host Name or Service Description field.

Alternatively, Event Adjustments can also be created starting from any existing Icinga 2 Event in the Monitoring, from the Event Details page.

Advance Search Filter

It is possible for a user to search event adjustments, according to their requirements using the search filter that supports search on the basis of hostname, service, description, start/end time or event type.

The Event Adjustment CLI Command¶

The event adjustment feature is also available through the CLI. Below you can find detailed descriptions of the available commands and their parameters.

Note

All timestamps in the commands below must be in the format YYYY-MM-DD hh:mm:ss and be expressed in your local timezone as set in PHP during the initial configuration.

Create

The create command lets you create a new event adjustment for a particular Monitored Object (host or service).

Usage:

# icingacli slm adjustments create [parameters]

Available Parameters:

–host-name:: (mandatory) Name of the host to which attach the event
–service-description:: (optional) Name of the service, running on host $host-name, to which to attach the event
–description:: (mandatory) Title for the event
–start:: (mandatory) Timestamp for the starting point of the event
–end:: (mandatory) Timestamp for the ending point of the event
–event-type:: (optional) State for the event; if not explicitly defined it will be automatically set to downtime. The event type must be one of the values in the table above that is available for the monitored object passed in the $host-name or $service-description parameters.

Example

I want to create an event adjustment for the host “my-host” to specify that this host was up and running yesterday night from 1 AM to 3 AM.

I then execute the following command:

icingacli slm adjustments create --host-name="my-host" --description="Wrong host state" --start="2019-12-18 01:00:00"  --end="2019-12-18 03:00:00" --event-type="up"

List

The list command lets you see existing event adjustments. The output will be a JSON object.

Usage:

# icingacli slm adjustments list

Edit

The edit command lets you alter the starting or ending time of an existing event adjustment given that adjustment’s ID, which you can obtain from the list command. Note that you cannot change the host or service name filters this way - you will have to delete and recreate the event adjustment. Also, if neither the –start nor the –end parameters are included, the event adjustment will not be changed.

Usage:

# icingacli slm adjustments edit [parameters]

Available Parameters:

–id:: (mandatory) The ID of the adjustment to change
–start:: (optional) Timestamp for the starting point of the event
–end:: (optional) Timestamp for the ending point of the event
–event-type:: (optional) State for the event. The event type must be one of the values in Table 15 above that are available for the monitored object pointed to in the event adjustment.

Delete

The delete command lets you delete an existing event adjustment given that adjustment’s ID, which you can obtain from the list command.

Usage:

# icingacli slm adjustments delete [parameters]

Available Parameters:

–id:: (mandatory) The ID of the adjustment to change

Outages¶

Annotations¶

Every outage can have an Outage Annotation that will be shown in the SLA report when rendered: it can be easily customized and supports markdown formats. You can add an annotation directly from SLM > Outage Annotations. In order to associate an annotation with the desired outage, you have to select a date between the start and the end of the outage itself.

Add Outage Annotation from monitoring event

The annotation can be also inserted directly from the monitoring event tab. Select the link under the “Outage Annotations”, in the outage event itself. The form for creating the annotation will be partially precompiled with the information related to the selected outage.

Resource Reports¶

To create an SLM resource report, you will need to:

Configure one or more customers and resource contracts in the SLM module
Create a new report in the Reporting module and set the following fields, which are all compulsory:
- Name: A name that uniquely identifies the report
- Timeframe: Selecting a value here defines for how much time the report will be generated.
- Report: Set this to SLM Resource Report, whereupon the form will add the following field.
- Customers: Choose for which customer you want to create the report. In Customers drop-down menu, you will be able to select only customers who either have access to the Analytics Module or have a role in common with the SLM user himself.
- Resource Contracts: Choose the contract, linked to the analytics dashboard for a selected customer.

After you click on “Create Report”, the report will appear in the list of available reports.

Within each report, you can read the details related to the selected contract. The SLM Resource Reports will contain all the static panels including panels inside the rows of a Grafana dashboard linked to the selected resource contract.