Viewing usage statistics of virtual services in Rational® Test Control Panel

You can use IBM® Rational® Test Control Panel to display the usage statistics of virtual services across Rational® Test Virtualization Server and IBM® Rational® Integration Tester.

About this task

Most of the sections are for Rational® Test Control Panel system administrators except for section B. Usage, which is for Rational® Test Control Panel users.

Procedure

A. Server Configuration

By default the metric data is stored in an H2 database in the Rational® Test Control Panel workspace. The H2 database does not scale to long-term usage. To enable long-term storage of metric data, you can edit the server configuration file of Rational® Test Control Panel to use a Cassandra database. For more information about downloading, installing, and setting up a Cassandra database, see Apache Cassandra.
1. Go to the Rational® Test Control Panel installation folder and locate the server configuration file. Typically on Windows™ systems, the file is in server_installation_directory\config and on non Windows™ systems, in server_installation_directory/config.
2. Open server.custom.xml in a text editor.
3. Edit that file to configure Rational® Test Control Panel with the details that are needed to communicate with a Cassandra database.
  
  For more information about a Cassandra database, see Apache Cassandra.
To change the interval in which metric data is reported, edit the Rational® Test Control Panel server configuration file.
1. Go to the Rational® Test Control Panel installation folder and locate the server configuration file. Typically, on Windows™ systems, the file is in server_installation_directory\config and on non Windows™ systems, in server_installation_directory/config
2. Open server.custom.xml in a text editor.
3. Edit the file and add the following code.
```
!--Metric clients report every 300 seconds (by default). Metrics can be gathered more regularly if higher precision is required, but this will increase the storage and network bandwidth used-->
<jndiEntry jndiName="metric/report_interval" value="300"/>
```

B. Usage

Open the Usage page in Rational® Test Control Panel to see usage metrics for stubs. For more information, see Navigating the user interface.
The metric data that is reported is as follows:
- The number of calls that are received by a stub. These calls are requests, messages, or other calls that are received by the stub.
- The number of calls that the stub virtualized. That is, the received calls that had their behavior changed, for example where the stub provided a response, or delayed response from the live system by the configured amount, or simulated an error response.
Metric data is reported every 5 minutes or when the last stub shuts down.
To see usage metrics for stubs, do one of the following tasks:
- Start stubs from Rational® Test Control Panel. For details, see Starting stubs by using the IBM Rational Test Control Panel method.
- Run stubs from the Rational® Integration Tester command-line (RunTests command) or Ant task. For details, see Running tests by using the command line or Running tests by using an Ant task.
- Run stubs from the Rational® Integration Tester interface. For details, see Executing a test asset.
Note: When domain-level security is enabled, the Usage page is only visible to users with the Rational® Test Control Panel system administrator role. When LDAP or Active Directory is in use, the system administrator role is assigned to user groups by the user who installs Rational® Test Control Panel. For more information about domain-level security, see Security considerations for Rational Test Control Panel.
By default, the results show usage data that is gathered over the last week, which is grouped by hour. To select a different view of the data, you can use the Period selections and associated controls. To filter results by domain if you are running stubs from Rational® Test Control Panel, use the Filter by domain field. To refresh the usage data, click .
To switch off metrics set the RTVS_METRIC_MODE environment variable to OFF for the IntegrationTester executable, the RunTests executable, the agent's RunTests executable, or the Ant task executable. Any value other than OFF results in an attempt to connect to the server identified by the RTVS_METRIC_URL environment variable or, if that is not set, the server that is chosen as the Rational® Test Control Panel server in the project settings.

Important: Using an empty RTVS_METRIC_URL is not equivalent to setting RTVS_METRIC_MODE=OFF.

C. Optional client configuration

By default Rational® Integration Tester and Rational® Test Virtualization Server report metrics to the Rational® Test Control Panel server configured in the Rational® Integration Tester project. You can override this default behavior and report metrics to a different server by one of the following ways:
- By setting an environment variable that is visible to the IntegrationTester executable, the RunTests executable, the agent's RunTests executable, or the Ant task executable. For example, on Windows™ Systems:
```
set RTVS_METRIC_URL=https://localhost:5443/metric
```
- By setting the path to a different server in the application.ini file, the IntegrationTester.ini , or RunTests.ini as a JVM argument. For example:
```
 -DRTVS_METRIC_URL=https://localhost:5443/metric
```
  The JVM argument takes precedence.
- By running Library Manager and adding the following option to the JVM Arguments section. For example:
```
 -DRTVS_METRIC_URL=https://localhost:5443/metric
```
- Metrics are reported to Rational® Test Control Panel by the RunTests engine and the Rational® Integration Tester workbench. If use of a corporate HTTP proxy is required to enable this connectivity, it can be configured by setting the http_proxy environment variable. An example syntax of http_proxy is:
```
http://my.proxy.com:3128
```
  Note: The RunTests engine is used in both Rational® Integration Tester, Rational® Test Virtualization Server and from the Rational® Integration Tester Ant task. The above advice applies to configure use of the corporate HTTP proxy with all of these applications.
By default Rational® Test Control Panel is configured to use HTTPS and all server certificates are trusted. To not trust all server certificates, you can set the truststore and password by one of the following ways:
- By setting environment variables that are visible to the IntegrationTester executable, the RunTests executable, the agent's RunTests executable, or the Ant task executable. For example, on Windows™,
```
 -DRTVS_METRIC_TRUSTSTORE=<path to truststore> -DRTVS_METRIC_PASSWORD=<password>
```
- By setting the truststore and password in the application.ini file, the IntegrationTester.ini , or RunTests.ini as a JVM argument. For example:
```
 -DRTVS_METRIC_TRUSTSTORE=<path to truststore> -DRTVS_METRIC_PASSWORD=<password>
```
  The JVM argument takes precedence.
- By running Library Manager and adding the following options to the JVM Arguments section. For example:
```
-DRTVS_METRIC_TRUSTSTORE=C:\Program Files\IBM\RTCP\usr\servers\defaultServer\resources\security\key.jks-DRTVS_METRIC_PASSWORD=password
```
Note: You must set the URL for the server per step 7 before you set the server truststore and password.

D. Deleting data

To delete old data, you can do one of the following options:
- When a Cassandra data store is used you can set a time-to-live (TTL) mechanism with the stored data, so data can be automatically removed. This mechanism is set up by changing the property kairosdb.datastore.cassandra.datapoint_ttl in server installation directory\usr\servers\defaultServer\apps\kairosdb.war\WEB-INF\kairosdb\conf\kairosdb.properties. To apply this setting, restart Rational® Test Control Panel.
- When the default H2 data store is used no automatic data removal is possible, the H2 data store can be purged by removing the directory C:\IBM\RTCP-Workspace\kairosdb\h2db while Rational® Test Control Panel is not running.
- Specific data point ranges can be deleted by using the KairosDB development interface on the system where Rational® Test Control Panel is installed at http://localhost:7828/.
  
  Note: The http://localhost:7828/ interface can be accessed only by browsers that are running on the same system as Rational® Test Control Panel. It cannot be accessed remotely.

E. Advanced client configuration

To store additional information against the metric data, you can set more environment variables for the IntegrationTester executable, the RunTests executable, the agent's RunTests executable, or the Ant task executable.
The following example adds who metadata to any metric data stored, which might enable more useful reports, for example, to report who is using the stubs the most. However, storing extra data has an extra cost on storage so you want to be conservative, especially if you are using only an H2 database rather than a Cassandra database.
```
set RTVS_METRIC_ALIAS_who=%USERNAME%
```
Note: You can also add fixed values by using Library Manager. By doing so, you keep the configuration within the Rational® Integration Tester Agent installation. For example, to record the Rational® Integration Tester Agent name that is running stubs, run Library Manager (on the system where Rational® Integration Tester Agent is installed) and add an entry on its own line to the text box labeled JVM Arguments:
```
-DRTVS_METRIC_ALIAS_agent=myAgent1
```
Restart the Rational® Integration Tester Agent and your stubs to enable the saving of the agent name.