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
  1. 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.

  2. 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.
      <!--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
  1. 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.

  2. To see usage metrics for stubs, do one of the following tasks:
    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.
  3. 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 Refresh chart data icon.
  4. 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
  1. 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.
  2. 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
  1. 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
  1. 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.