Configuration¶
Reporting User Role Management¶
The SLM module relies on the Reporting module to manage and show the reports. Therefore, user permissions for creating, modifying and visualizing the reports should be granted within the Reporting section in . This is the list of available permissions that can be used to extend the range of available actions for a specific user:
Full Module Access: gives unlimited access on the Reporting module.
General Module Access: allows to access the reports in read-only mode.
reporting/reports: allows to manage the reports.
reporting/schedules: allows to manage the report scheduled actions.
reporting/templates: allows to manage the report templates.
reporting/timeframes: allows to manage the report timeframes.
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.
Note
Before configuring a new report, make sure appropriate permissions are granted to the user’s NetEye role. If the user has to to define a new report he should have at least the General module access enabled both for SLM Module and for Reporting, and the reporting/reports permission enabled under the Reporting section.
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 Adjustmentflag 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 Availabilityflag 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 () 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 ) 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 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 14 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 14 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¶
Note
Before configuring a new report, make sure appropriate permissions are granted to the user’s NetEye role. If the user has to to define a new report he should have at least the General module access enabled both for SLM Module and for Reporting, and the reporting/reports permission enabled under the Reporting section.
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.
