ITRS Synthetic Monitoring
Overview Copied
ITRS Synthetic Monitoring (powered by Apica) allows you to monitor websites, web applications, and web services. The integration with Geneos enables you to retrieve all the checks and alert statistics configured in the Apica dashboard and display them as dataviews in Geneos.
The ITRS Synthetic Monitoring integration provides a Gateway configuration file that enables monitoring of the Apica environment through a set of pre-configured Toolkit samplers. The script can be configured by a set of environment variables and command line options.
This guide walks you through the integration process.
Audience Copied
This user guide is intended for users who will be setting up, configuring, troubleshooting and maintaining this integration. This is also intended for users who will be using Active Console to monitor data from the Apica environment.
You should be familiar with Python and with general administration of the Apica environment.
Prerequisites Copied
The following requirements must be met before the installation and setup of the template:
- Python 2.7 or newer, or Python 3.6 or newer
- pip module
- Python Requests module
Installation procedure Copied
The Synthetic Monitoring integration is largely pre-configured and involves three primary steps:
- Download the integration files from the resources site.
- Load the integration file in the Gateway Setup Editor.
- Associate the samplers with a managed entity.
Note
The include files are intended to be read-only and should not be edited (unless the integration specifically requires for them to be modified). This is because include files can be shared between a few instances of a Gateway and best practice is to share them in their default state. It is also to make the upgrades and maintenance process of the integration files easier. All configuration should be carried out in your local Gateway files instead.
Download the integration files Copied
- Download the integration package
geneos-integration-apica-<version>.zipfrom the Downloads site. - As a best practice, save the files on the same machine where your Gateway is running.
The integration package includes a number of files. These are the files that determine the integration setup:
include/apicaMonitoring.xml— Gateway configuration file (also called an include file) containing Toolkit samplers configured for Synthetic Monitoring.scripts/Get_Apica_Checks.py— Python script that calls Apica API and returns a JSON format. The JSON values are then processed in a CSV format and displayed in Active Console.
Load the integration files Copied
To load the integration files into the Gateway Setup Editor, follow these steps:
- Open Gateway Setup Editor.
- In the Navigation panel, click Includes to create a new file.
- Enter the location of the file to include in the Location field. In this example, it is the
include/apicaMonitoring.xml. - Update the Priority field.
- Expand the file location in the Include section.
- Select Click to load.
- Click Yes to load the new include file.
Success
Gateway configuration now appears in the Includes section.
Associate the samplers with a managed entity Copied
After you have loaded the configuration file, the Synthetic Monitoring monitoring samplers become available for use. These samplers are associated with a pre-defined Type. To associate the samplers with a managed entity, follow these steps:
- In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder.
- Under the Basic tab for the new managed entity, add a pre-configured
Apicatype. - Specify the environment associated with the samplers. By default, this is
ApicaConfiguration. - Apply the managed entity to the running Netprobe.
- Click Validate current document
to check your configuration. - Click Save current document
to apply the changes.
Success
After you save your changes to the managed entity, the Apica dataviews appear under the managed entity on the state tree.
For more information about include files, see the Gateway Setup Editor.
Environment configuration Copied
The default environment configuration is created by the apicaMonitoring.xml script. You can create a new environment or modify the default ApicaConfiguration environment variables according to your system.
Note
Standard variable scoping rules apply when variable reference is used in include files. Please take note of that when creating your own variables. For more information, see Variable Scoping and Resolution.
Environment variables Copied
The apicaMonitoring.xml script provides the variables that are set in the Environments section. They are configured to ensure that the integration monitors your target Apica environment.
| Variable | Type | Description |
|---|---|---|
| APICA_USER | String |
Username you are connecting with. |
| APICA_PASS | String |
Password for the specified user. |
| APICA_SVR | String |
Server you are connecting to. |
| PYTHON_PATH | String | Location of the sampler script. It can change depending on the environment. |
| GROUPNAME | String | Folder name of the dataview group. |
| APICA_SAMPLETIME | Integer | Amount of time for dataviews to resample (in seconds). |
Command line options Copied
Command line options can be used instead of, or along with, the Environment variables.
| Option (long) | Option (short) | Type | Description |
|---|---|---|---|
| --user | -u | String |
Username you are connecting with. |
| --password | -pw | String |
Password for the specified user. |
| --server | -s | String |
Server you are connecting to. |
For example:
-
If you want to retrieve a particular group using a command line option:
./scripts/Get_Apica_Checks.py -s <server> -u <username> -pw <password> -g YourGroup "GroupBAR" -
If you want to retrieve a particular group using environment variables:
export APICA_SERVER=<server> export APICA_USER=<username> export APICA_PASS=<password> export APICA_GROUP_A=YourGroup export APICA_GROUP_FOO="GroupBAR" ./scripts/Get_Apica_Checks.py -
When you declare both groups and subgroups, the script iterates through each check group and looks for the specified subgroups. You can use environment variables or command line options for this. Command line options:
$ ./scripts/Get_Apica_Checks.py -s <server> -u <username> -pw <password> \ -g YourGroup \ -sg YouSubGroup "SubGroup FOOBAR";Environment variables:
export APICA_SERVER=<server> export APICA_USER=<username> export APICA_PASS=<password> export APICA_GROUP_A=YourGroup export APICA_SUBGROUP_A=YourSubGroup export APICA_SUBGROUP_FOO="SubGroup FOOBAR" ./scripts/Get_Apica_Checks.py -
You can combine environment variables with the command line options:
export APICA_SERVER=<server> export APICA_USER=<username> export APICA_PASS=<password> export APICA_GROUP_A=YourGroup ./scripts/Get_Apica_Checks.py -g "GroupBAR" -sg "SubGroup FOOBAR"
Knowledge base Copied
Knowledge base links are configured to redirect users to the detail view of the selected metric in the Apica dashboard. The links are created by concatenating the dashboard link which is configured as a URL template and the row name value (which is the Check ID). You can edit the links or change the labels where required. For more information on managing knowledge base article links, see Knowledge Base in Gateway Advanced Features.
Metrics and dataviews Copied
The sections below list metrics and example dataviews available with the Synthetic Monitoring integration.
By default, the integration displays dataviews from the following samplers:
- Apica-AllChecks
- Apica-Severity.
Two additional dataviews are available when you set up the following samplers:
- Apica-GroupChecks
- Apica-SubGroupChecks.
If you want to drill down to more details of a metric, follow these steps:
- Right-click a field with an information icon
- Go to Knowledge base.
- Click Apica Check Page.
You are redirected to Apica dashboard with the details of the selected metric.
Apica-AllChecks Copied
This dataview displays all metrics of the configured checks from your Apica environment.
| Headline field | Description |
|---|---|
| execDuration |
Elapsed time for the Toolkit plug-in to run the script. Unit: seconds |
| Column Name | Description |
|---|---|
| enabled | Flag indicating whether the check is enabled or not. If the check is disabled, it will not run. |
| severity |
Severity type. The following severities are available: I — Information W — Warning E — Error F — Fatal |
| sla_percent_current_month | SLA percentage for the specified time threshold, in this case current month. |
| name | Name of the check. |
| location | Country and city of origin for the check. |
| check_type_api |
Check type API Example: browser |
| check_type_name |
Check type name Example: Firefox |
| timestamp_utc | Time when the last check ran (UTC). |
| url | Target URL for the check. |
| message | Messages generated by the check. |
| value (unit) | Value returned for the check. The value and units depend on what is configured for the specific check (for example: total page size - bytes, total browser render time - milliseconds). |
| interval_seconds | Frequency of execution of the check. If checks are executed manually, the value is shown as 0. |
| attempts | Number of attempts that can be made to verify the results. |
| groups | Name of a group that is checked. |
| subgroups | Name of a subgroup that is checked. |
Apica-Severity Copied
| Headline field | Description |
|---|---|
| execDuration |
Elapsed time for the Toolkit plug-in to run the script. Unit: seconds |
| Column Name | Description |
|---|---|
| Name (id) | Name of a group and subgroup. Subgroup names are indented. |
| Fatal | Number of alerts that are of Fatal severity type. |
| Error |
Number of alerts that are of Error severity type. |
| Warning | Number of alerts that are of Warning severity type. |
| Information | Number of alerts that are of Information severity type. |
Apica-GroupChecks Copied
This dataview displays all metrics of the configured checks relevant to the selected Groups.
Apica-GroupChecks sampler is configured using the same keys as Apica-AllChecks sampler. Refer to the Apica-AllChecks for more information.
By default, this sampler is not set up to display a dataview. You need to configure it to be able to view the metrics by associating it with a managed entity.
Apica-SubGroupChecks Copied
This dataview displays all metrics of the configured checks relevant to the selected SubGroups.
Apica-SubGroupChecks sampler is configured using the same keys as Apica-AllChecks sampler. Refer to the Apica-AllChecks for more information.
By default, this sampler is not set up to display a dataview. You need to configure it to be able to view the metrics by associating it with a managed entity.
