Viewing usage statistics of virtual services in HCL Quality Server

You can use HCL Quality Server to display the usage statistics of virtual services across HCL OneTest™ Virtualization and HCL OneTest™ API.

About this task

Most of the sections are for HCL Quality Server system administrators except for section B. Usage, which is for HCL Quality Server users.

Procedure

A. Server Configuration

By default the metric data is stored in an H2 database in the HCL Quality Server 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 HCL Quality Server to use a Cassandra database. For more information about downloading, installing, and setting up a Cassandra database, see Apache Cassandra.
1. Go to the HCL Quality Server installation folder and locate the server configuration file. Typically on Windows™ systems, the file is in <HCL Quality Server installation directory>\config and on non Windows™ systems, in <HCL Quality Server installation directory>/config.
2. Open server.custom.xml in a text editor.
3. Edit that file to configure HCL Quality Server 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 HCL Quality Server server configuration file.
1. Go to the HCL Quality Server installation folder and locate the server configuration file. Typically, on Windows™ systems, the file is in <HCL Quality Server installation directory>\config and on non Windows™ systems, in <HCL Quality Server installation directory>/config
2. Open server.custom.xml in a text editor.
3. Edit the file and add the following code.
```

<jndiEntry jndiName="metric/report_interval" value="300"/>
```

B. Usage

Open the Usage page in HCL Quality Server 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 HCL Quality Server. For details, see Starting stubs by using the HCL Quality Server method.
- Run stubs from the HCL OneTest™ API command-line (RunTests command) or Ant task. For details, see Run tests by using the command line or Run tests by using an Ant task.
- Run stubs from the HCL OneTest™ API 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 HCL Quality Server 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 HCL Quality Server. 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 HCL Quality Server, 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 HCL Quality Server 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 HCL OneTest™ API and HCL OneTest™ Virtualization report metrics to the HCL Quality Server server configured in the HCL OneTest™ API 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 HCL Quality Server by the RunTests engine and the HCL OneTest™ API 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 HCL OneTest™ API, HCL OneTest™ Virtualization and from the HCL OneTest™ API Ant task. The above advice applies to configure use of the corporate HTTP proxy with all of these applications.
By default HCL Quality Server 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™ Systems:
```
set RTVS_METRIC_TRUSTSTORE=<path to truststore>
set RTVS_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 <HCL Quality Server installation directory>\usr\servers\defaultServer\apps\kairosdb.war\WEB-INF\kairosdb\conf\kairosdb.properties. To apply this setting, restart HCL Quality Server.
- 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:\HCL®\HQS-Workspace\kairosdb\h2db while HCL Quality Server is not running.
- Specific data point ranges can be deleted by using the KairosDB development interface on the system where HCL Quality Server 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 HCL Quality Server. 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 HCL OneTest™ API Agent installation. For example, to record the HCL OneTest™ API Agent name that is running stubs, run Library Manager (on the system where HCL OneTest™ API 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 HCL OneTest™ API Agent and your stubs to enable the saving of the agent name.