Geneos ["Geneos"]
You are currently viewing an older version of the documentation. You can find the latest documentation here.
["Geneos > Netprobe"]["User Guide"]

ITRS Synthetic Monitoring

Overview

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

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

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

The Synthetic Monitoring integration is largely pre-configured and involves three primary steps:

  1. Download the integration files from the resources site.
  2. Load the integration file in the Gateway Setup Editor.
  3. 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

  1. Download the integration package geneos-integration-apica-<version>.zip from the ITRS Downloads site.
  2. 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

To load the integration files into the Gateway Setup Editor, follow these steps:

  1. Open Gateway Setup Editor.
  2. In the Navigation panel, click Includes to create a new file.
  3. Enter the location of the file to include in the Location field. In this example, it is the include/apicaMonitoring.xml.
  4. Update the Priority field.
  5. Expand the file location in the Include section.
  6. Select Click to load.
  7. Click Yes to load the new include file.

Gateway configuration now appears in the Includes section.

Associate the samplers with a managed entity

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:

  1. In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder.
  2. Under the Basic tab for the new managed entity, add a pre-configured Apica type.
  3. Specify the environment associated with the samplers. By default, this is ApicaConfiguration.
  4. Apply the managed entity to the running Netprobe.
  5. Click Validate current document to check your configuration.
  6. Click Save current document to apply the changes.

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

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 in User Variables and Environments.

Environment variables

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

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

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

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:

  1. Right-click a field with an information icon
  2. Go to Knowledge base.
  3. Click Apica Check Page.

You are redirected to Apica dashboard with the details of the selected metric.

Apica-AllChecks

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

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

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

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.