Use Cases¶

Put Test Case in Production¶

This section explains how to put an Alyvix test case in production.

Prerequisites¶

In order to be able to put a test case in production, the Alyvix Node should be installed as described in section Install an Alyvix Node, and then configured in the Director Module. You should also follow the Alyvix Node Authentication guide to configure secure communication with NetEye.
A new test case file should be created using Alyvix built-in tools.
To run a test case with an Alyvix Service, the Node must have a valid license. You can download the license request key and then upload the obtained license activation key directly from NetEye, as described in the License Tab section.

Note

The interval between obtaining the license request key and activating the license in NetEye may take some time. Thus, make sure your license is activated before you start working with sessions and test cases.

After the Alyvix Node setup process including all the above has been completed, you can proceed with creating your first Alyvix session.

Step 1. Create Alyvix Sessions¶

A test case should be run within a session. To add it, switch to the nodes list, select the Alyvix node and click the New Session button in the Sessions Tab.

Step 2. (Optional) Create a Time Period¶

If you want to execute your Test Case every day, without any time limitations, you can safely skip this step.

If instead you want to run the Test Case only during a certain time of the day or on certain days of the week (or even on certain dates), you should first create a Time Period which defines the exact hours and days when the Test Case must be executed.

To create the Time Period navigate to Icinga Director / Timeperiods / Timeperiods / Add and define the Name and Display Name of the Time Period. If you cannot access the Icinga Director module, please ask your NetEye administrator to create such Time Period.

Note

Please do not use the Include period and Exclude period functionalities because Alyvix does not support them and will not allow you to use such Time Period.

Once the Time Period is created, use the Ranges tab to define in which days and/or hours you want the Alyvix Test Case to be run.

Note

If you modify an existing Time Period which is already associated with an Alyvix Test Case, you should synchronize the changes with Alyvix in the Node’s Time Periods tab. Click the Sync with NetEye button to sync all time periods definitions with the Alyvix Node, as described in the Time periods Tab section.

Step 3. Create Alyvix Test Cases¶

Once you have added a session on the Alyvix node, switch to the test cases list and click Create.

Select the node to run a test case on
Specify its definition by choosing the file previously created on the Alyvix Node as stated in Prerequisites.

Step 4. Run Test Cases¶

At this point, the test case you created is not running in its session. To enable its execution, click the arrow button in correspondence with the session previously defined to open the session workflow controls.

Enable the session if needed
Enable the test case in the session using the associated toggle
Start the session by enabling its workflow

Step 5. Check Test Case Results¶

Once the test case has been executed, switch to the Reports Tab to visualize its runs.

Click a specific run to open the Report view, which shows the details and all its transactions
Select a transaction to consult its parameters and understand how it performed.

Visualize Alyvix Performance Metrics¶

As a user, I want to be able to collect, explore and understand data on the Test Cases performance metrics sent by an Alyvix Session to an InfluxDB, so that I can analyze the test case performance based on the collected metrics data.

Prerequisites¶

In order to be able to collect the performance metrics generated by your Alyvix node in NetEye, the neteye-alyvix module must be enabled for the NetEye Tenants to which the metrics belong to.

To enable the module for an already existing Tenant, please refer to the neteye tenant config modify. section.

To create a Tenant and directly enable the module for it, please refer to the neteye tenant config create section.

Step 1. Put a Test Case in Production¶

First of all, ensure Alyvix is set to generate the metrics that you would like to collect, putting a Test Case in production.

Step 2. Configure the Alyvix Node¶

After having configured a Test Case to generate metrics, the connection between the Alyvix node and NetEye must be configured. The configuration procedure depends on the architecture of the Alyvix node. The node can belong to one of the following types:

Please make sure to follow the steps related to the architecture of your Alyvix node.

Multitenant - Tenant Specific or Single Tenant - Via Satellite

On the Alyvix node, upload the certificate and key to be used to send the metrics to NetEye. To do this, upload to the Alyvix node the certificate that can be found on the chosen Satellite in the /neteye/shared/nats-server/conf/certs/<tenant>-alyvix_metrics.crt.pem file, with the corresponding key in the /neteye/shared/nats-server/conf/certs/private/<tenant>-alyvix_metrics.key.pem file.
On the Alyvix node upload the CA certificate of the NetEye node chosen as target of the Alyvix metrics. This can be found under the /root/security/ca/root-ca.crt file of that NetEye node.
Configure on the Alyvix node, the NATS profile, as explained in the official Alyvix Service documentation. Specify, where needed:
- The hostname of the NetEye Satellite chosen as target of the Alyvix metrics. This can be retrieved by running, on the chosen NetEye Satellite, the . /usr/share/neteye/scripts/rpm-functions.sh && get_neteye_hostname command.
- The NATS default port 4222 as the connection port
- The path to the previously uploaded certificate, key and CA
- The NATS subject as alyvix.metrics
Connect the configured NATS profile, as explained in the official Alyvix Service documentation, to an existing Alyvix session for which you would like to collect the metrics.

Multitenant - Tenant Shared

Configure a Tenant for each session by entering the Tenant name in the Sessions Tab. Furthermore use the neteye alyvix-node setup to automatically configure the NATS channels for the direct communication to the NetEye Master.

Single Tenant - Direct to Master

Use the neteye alyvix-node setup command to automatically configure the NATS channels for the direct communication to the NetEye Master. Please note that in this case the Tenant related to all the sessions on the Alyvix node will be the Master Tenant.

Step 3. Configure the retention of your metrics¶

By default, the retention of the collected Test Cases performance metrics is of 365 days. If you would like to specify a different retention for a specific Tenant, please refer to the tenant configuration.

Step 4. Enjoy your metrics¶

On the NetEye Master, metrics generated during the run of Alyvix Session, for which NATS - InfluxDB connection was configured, are stored in the <tenant>-alyvix InfluxDB database. You can now consult them directly in InfluxDB or explore the data arranged in easy to read and meaningful dashboards via the The ITOA Module.

Make sure that you choose the correct Grafana Organization associated to the Tenant to which the performance metrics belong to.

Switching to a new Alyvix Performance metrics format

Starting from version 2.1.0, Alyvix Service returns the performance metrics of the Test Cases running inside the same session as separate InfluxDB measurements, in contrast with the single measurement exposed in previous versions.

The built-in dashboards available in the The ITOA Module are fully compatible with the new format.

It is important to take into consideration that the Alyvix Test Cases Performance metrics collected with Alyvix Service 2.1.0 or above will be stored in different InfluxDB measurements than those collected with previous versions.

For this reason, we provide a script to migrate already collected Alyvix Performance metrics to the new format in the InfluxDB database dedicated to their Tenant. This will also allow their inclusion in the available built-in dashboards. Please note that the script will not delete the already collected metrics but will copy them in the correct measurements, ensuring that no data is loss during the migration process.

To migrate the already collected metrics to the new measurements, after having performed the configuration outlined above, the following script is to be run:

bash /usr/share/neteye/scripts/alyvix/migrate_alyvix_influx_measurements.sh \
  "<source-database>" "<source-measurement>" "<target-tenant>"

with the following parameters:

source-database: representing the database in InfluxDB where the previously collected metrics are stored
source-measurement: representing the measurement in the provided InfluxDB database where the previously collected metrics are stored
target-tenant: the Tenant to which specified metrics belong. They will be migrated to a separate measurement in the InfluxDB database dedicated to the Alyvix metrics for this Tenant.

Moreover, in case the source InfluxDB node differs from the destination one, the script can be launched specifying four more parameters to define the connection to the source InfluxDB instance:

bash /usr/share/neteye/scripts/alyvix/migrate_alyvix_influx_measurements.sh \
  "<source-database>" "<source-measurement>" "<target-tenant>" \
  "<source-node-hostname>" "<source-node-port>" \
  "<source-node-admin-user>" "<source-node-admin-password>"

where the new parameters are:

source-node-hostname: the hostname of the source InfluxDB instance
source-node-port: the port where InfluxDB is listening for connections on the source host
source-node-admin-user: username of a user with administrator privileges on the source InfluxDB instance
source-node-admin-password: password of the specified administrator user

Note

The target InfluxDB node is inferred from the specified target Tenant, as configured in the tenant configuration.

Visualize Alyvix Performance Metrics in Elastic Observability¶

As a user, I want to be able to collect, explore and understand data on the Test Cases performance metrics sent by an Alyvix Session to the Elastic Stack, so that I can analyze the Test Cases performance based on the collected metrics data.

This guide will explain how to configure Alyvix nodes to send performance metrics to the Elastic APM server using the OpenTelemetry (OTEL) protocol, and how to visualize these metrics in the Elastic Observability UI.

Prerequisites¶

In order to be able to collect the performance metrics generated by your Alyvix node in NetEye, the following prerequisites must be met:

The Alyvix node must be updated to Alyvix Service version 2.7.2 or later.
The neteye-alyvix and the neteye-elastic-stack modules must be installed in the NetEye system and enabled for the NetEye Tenants to which the metrics belong to. Please refer to the Additional NetEye Components for installing additional NetEye modules and to the neteye tenant config modify or the neteye tenant config create section to enable the module for an already existing Tenant or to create a Tenant and directly enable the module for it.
The Alyvix node should be reachable by the NetEye Master.

Note

If the Alyvix node is a Multitenant - Tenant Specific or a Single Tenant - Via Satellite, and the Alyvix node cannot be reached directly by the NetEye Master, then the OTEL configuration should be done manually on the Alyvix node. To perform the configuration of such Alyvix nodes, you can follow the dedicated section about how to Configure the Alyvix Node Manually.
The TCP port 8200 of the NetEye Master or the NetEye Satellite, depending on the architecture of the Alyvix node, should be reachable by the Alyvix node.
If the Alyvix node is connected to a NetEye Satellite, the Elastic APM Server should be installed and configured on the NetEye Satellite.

Step 1. Put a Test Case in Production¶

First of all, ensure Alyvix is set to generate the metrics that you would like to collect, putting a Test Case in production.

Step 2. Configure the Alyvix Node¶

After having configured a Test Case to generate metrics, the OTEL connection between the Alyvix node and the Elastic APM server must be configured.

Use the neteye alyvix-node setup command to automatically configure the OTEL connection between the Alyvix node and the NetEye Master or the NetEye Satellite, depending on the architecture of the Alyvix node. The command will automatically configure the Alyvix node to send the metrics to the APM Server running on the NetEye Master or on the NetEye Satellite. The command will take care of creating the necessary authentication credentials for the Alyvix node on the APM server related to every tenant that is using the Alyvix node.

Step 3. Enjoy your metrics¶

Metrics generated during the run of Alyvix Session will be automatically collected by the APM server running on the Elastic Agent of the NetEye Master or the NetEye Satellite and stored in Elasticsearch. You can then visualize the collected metrics in the Elastic Observability UI by navigating to Observability ‣ Applications in the Kibana web interface. You will find all the Alyvix Test Cases metrics under the ‘Alyvix’ Service.

Configure the Alyvix Node Manually¶

If the Alyvix node is connected to a NetEye Satellite and is not reachable by the NetEye Master, the neteye alyvix-node setup command fails since it cannot reach the Alyvix node and thus it cannot configure the OTEL connection. In this case, you can configure the OTEL connection manually on the Alyvix node by following these steps:

On the NetEye Master, run the following command to generate the OTEL configuration payload to be used on the Alyvix node:
```
neteye alyvix-node print-otel-configuration --node-name NODE_NAME --tenant-name TENANT_NAME
```
Replace NODE_NAME with the hostname of the Alyvix node and TENANT_NAME with the name of the Tenant. This command will generate the OTEL configuration payload and the authentication credentials for the Alyvix node to send the metrics to the NetEye Satellite belonging to the specified Tenant and it will save the payload in a file in the /tmp directory, named otel_config_<tenant_name>_<node_name>.json.
On the NetEye Satellite, or any host that can reach the Alyvix node, send the generated OTEL configuration payload to the Alyvix node by running the following command:
```
curl -X POST https://<ALYVIX_NODE_IP>/v5/super-admin/otel \
-H "Content-Type: application/json" -H "Authorization: Bearer <JWT_TOKEN>" \
-d @<OTEL_CONFIGURATION_PAYLOAD_FILE>
```
Where:
- <ALYVIX_NODE_IP> is the IP address of the Alyvix node.
- <JWT_TOKEN> is the JWT token needed to authenticate on the Alyvix node. The JWT can be generated by running the icingacli neteye jwt create command on the Icingaweb2 active node on the NetEye Master.
- <OTEL_CONFIGURATION_PAYLOAD_FILE> is the OTEL configuration payload file generated by the neteye alyvix-node print-otel-configuration command.
Once the OTEL configuration payload is sent to the Alyvix node, the Alyvix node should be able to send the metrics to the APM server running on the NetEye Satellite using the port 8200.