Resource Monitoring Agents

For testing, you would need many hosts. For example, you might have one host with the application server, another host with the database server, and some hosts to apply the user load. Due to network or firewall issues, sometimes, it becomes difficult for multiple hosts to connect to each other. Resource Monitoring Agents are installed on the target hosts so that they can establish a connection with HCL OneTest™ Server to gather resource statistics of the target host.

The agents always try to connect with the server through the HTTPS protocol. You must install the agent and start it. From the Resource Monitoring Service dashboard, you can copy the command lines to download the .jar files or to run the agents. When you stop the agent, the data sources that you have already added persist but the live data will not be available.

The following tasks explain how you can install and start the Resource Monitoring Agents:

Installing Resource Monitoring Agents

You must install the Resource Monitoring Agents on the target host for which you want to collect the performance statistics. The agents establish a connection with the Resource Monitoring service.

Procedure

Start HCL OneTest Server and access the Resource Monitoring service from the target host for which you want to collect performance statistics.
To download the agent, click Download the Jar File. You can also use curl and wget commands to download the agent without accessing the Resource Monitoring web UI.
```
curl -O -J https://hostName/rm/agent-jar
wget --content-disposition https://hostName/rm/agent-jar
```

To run the agent, in the command prompt, specify the directory path that contains the agent jar file and pass this command: On Windows:

set HCL_ONETEST_OFFLINE_TOKEN=(Enter your offline token here)
java -jar (Enter the name of the downloaded jar file here) --serviceUrl=https://hostName/rm --projectId=<project_id>

On Linux:

sudo HCL_ONETEST_OFFLINE_TOKEN=(Enter your offline token here) java -jar (Enter the name of the downloaded jar file here) --serviceUrl=portNumber/rm --projectId=<project_id>

Results

If the agent is started, it is displayed in the list of Connected Resource Monitoring Agents with the host name and status of the agent.

Starting the RM Agent as a service on Windows

To ensure that the Resource Monitoring Agent starts by itself when the host is restarted, you can set up the environment in such a way that the Resource Monitoring Agent can be started as a service.

Before you begin

Previously to starting a Resource Monitoring Agent as a service on Windows, you need to have:

Java 8 installed on the host.
HCL OneTest Server added to the PATH environment variable.
An offline token to connect the agent securely with appropriate permissions. You can create an offline token from the User menu of the Resource Monitoring dashboard or you can re-use your active offline token. The token expires if it is not used for a month.

Procedure

Download the latest release of winsw from this page. You can choose to download WinSW.Net2.exe or WinSW.Net4.exe depending on the version of .Net framework that you already have on the host Windows.
Create a folder on your local hard drive like RMAgent-winservice.
Copy the downloaded executable to this new folder and rename the file to RMAgent-winservice.exe.
Create a new text file in the same folder and name it RMAgent-winservice.xml.

To set up the offline token, copy and adapt the following content to this new RMAgent-winservice.xml file:

<service>
      <id>RMAgent-winservice</id>
      <name>Resource Monitoring Agent</name>
      <description>This service runs the Resource Monitoring Agent.</description>
      <executable>java</executable>
      <env name="HCL_ONETEST_OFFLINE_TOKEN" value="(Enter your offline token here"/>
      <arguments>-jar %BASE%\RMAgent.jar --serviceUrl=https://<service-host>/rm --projectId=<projet-id> --trustServiceCertificate --autoUpgradeDownloadThen=execute:cmd,/c,start,%BASE%\auto-upgrade.bat</arguments>
      <onfailure action="restart" delay="10 sec"/>
      <logmode>rotate</logmode>
</service>

Note:

Replace <service-host> by the host name of the host that runs HCL OneTest Server.
Replace <project-id> which is the number you'll find after /projects/ in the browser's URL when browsing to this project.

Create a new text file in the same folder and name it auto-upgrade.bat.

To upgrade the agent jar file automatically, copy the following content to this new file:

@echo off
for /f "tokens=*" %%a in ('dir /b /od %BASE%\com.hcl.test.rm.agent-*.jar') do set newest=%%a
%BASE%\RMAgent-winservice.exe stop
del %BASE%\RMAgent.jar
mklink %BASE%\RMAgent.jar %BASE%\%newest%
%BASE%\RMAgent-winservice.exe start

Start the command prompt as an administrator and change the directory to the newly created directory RMAgent-winservice.
Download the agent jar file from the Resource Monitoring web page and save it to the same directory.
In the command prompt, type the following command to create a symbolic link named RMAgent.jar to the agent jar file:
```
mklink RMAgent.jar com.hcl.test.rm.agent-<version-and-datetime>.jar
```

Type the following commands:

RMAgent-winservice install

RMAgent-winservice start

In the Services Windows application, you can check whether the service is up and running.
You can see in the Resource Monitoring dashboard whether the Resource Monitoring Agent is disconnected or connected.

What to do next

The Resource Monitoring Agents write the logs to the same folder in files named RMAgent-winservice.out.log, RMAgent-winservice.err.log and RMAgent-winservice.wrapper.log. Look at those files if the Windows Service for the Agent is not started or if it does not appear to be connected to the Resource Monitoring Service.

For information about other winsw commands, see its documentation.

Starting the RM Agent as a service on Linux

To ensure that the Resource Monitoring Agent starts by itself when the host is restarted, you can set up the environment in such a way that the Resource Monitoring Agent can be started as a service.

Before you begin

Previously to starting a Resource Monitoring Agent as a service on Windows, you need to have:

Java 8 installed on the host.
HCL OneTest Server added to the PATH environment variable.
An offline token to connect the agent securely with appropriate permissions. You can create an offline token from the User menu of the Resource Monitoring dashboard or you can re-use your active offline token. The token expires if it is not used for a month.

About this task

This topic relies on systemd services that is the default on most modern Linux distributions. Other ways may require adaptations of the instructions but the provided script will be a good basis in most cases.

Procedure

Create a folder on your local hard drive like /opt/RMAgent-linuxservice.
Download the agent jar file from the Resource Monitoring web page and save it to the same directory. For information about downloading the agent, see Installing Resource Monitoring Agents.
Create a new file /etc/systemd/system/RMAgent-linuxservice.service.

Add the following content to this new file:

[Unit]
Description = Resource Monitoring Agent
After = network.target

[Service]
Type = forking
ExecStart = /opt/RMAgent-linuxservice/RMAgent-linuxservice.sh start
ExecStop = /opt/RMAgent-linuxservice/RMAgent-linuxservice.sh stop
Restart = on-failure
RestartSec = 10

[Install]
WantedBy = multi-user.target

Create another file /opt/RMAgent-linuxservice/RMAgent-linuxservice.sh.

#!/bin/sh

#!/bin/sh

# Update the 3 following variables with the Server's host name, project id and offline token:
SERVICE_URL=https://<hostname>/rm 
PROJECT_ID=<project-id>
export HCL_ONETEST_OFFLINE_TOKEN=<offline-token>

ARGS="--serviceUrl=$SERVICE_URL --projectId=$PROJECT_ID --trustServiceCertificate --autoUpgradeDownloadThen=exitFailure"
SCRIPT=$(readlink -f "$0")
RMAGENT_HOME=$(dirname "$SCRIPT")

# Ensure we're using the latest downloaded jar file
PATH_TO_JAR=`ls -t $RMAGENT_HOME/com.hcl.test.rm.agent-*.jar | head -1`
if [ -z "$PATH_TO_JAR" ]
then
  cd $RMAGENT_HOME && { curl -k -O -J $SERVICE_URL/agent-jar; cd -; }
  PATH_TO_JAR=`ls -t $RMAGENT_HOME/com.hcl.test.rm.agent-*.jar | head -1`
  if [ -z "$PATH_TO_JAR" ]
  then
    echo "Start the server at $SERVICE_URL to allow download of the latest agent jar file"
    echo "Exiting..."
    exit 1
  fi
fi
SERVICE_NAME="Resource Monitoring Agent"
#Pid file will reside in this script’s folder
PATH_TO_PID=$RMAGENT_HOME/RMAgent-pid
#Log file will reside in this script’s folder
PATH_TO_LOG=$RMAGENT_HOME/RMAgent.log

case $1 in
    start)
        echo "Starting $SERVICE_NAME ..."
        if [ ! -f $PATH_TO_PID ]; then
            nohup java -jar $PATH_TO_JAR $ARGS >> $PATH_TO_LOG 2>&1 &
                        echo $! > $PATH_TO_PID
            echo "$SERVICE_NAME started ..."
        else
            echo "$SERVICE_NAME is already running ..."
        fi
    ;;
    stop)
        if [ -f $PATH_TO_PID ]; then
            PID=$(cat $PATH_TO_PID);
            echo "$SERVICE_NAME stopping ..."
            kill $PID;
            echo "$SERVICE_NAME stopped ..."
            rm $PATH_TO_PID
        else
            echo "$SERVICE_NAME is not running ..."
        fi
    ;;
    restart)
        if [ -f $PATH_TO_PID ]; then
            PID=$(cat $PATH_TO_PID);
            echo "$SERVICE_NAME stopping ...";
            kill $PID;
            echo "$SERVICE_NAME stopped ...";
            rm $PATH_TO_PID
            echo "$SERVICE_NAME starting ..."
            nohup java -jar $PATH_TO_JAR $ARGS >> $PATH_TO_LOG 2>&1 &
                        echo $! > $PATH_TO_PID
            echo "$SERVICE_NAME started ..."
        else
            echo "$SERVICE_NAME is not running ..."
        fi
    ;;
esac

Note:

Replace <service-hostname> by the host name of the host that runs HCL OneTest Server.
Replace <project-id> which is the number you'll find after /projects/ in the browser's URL when browsing to this project.

Results

The Resource Monitoring agent will start automatically when the host restarts.

Starting a Java Virtual Machine

To monitor the Resource Monitoring data from a Java Virtual Machine, you must start the Java Virtual Machine. Some parameters must be set in the command line before running the Java Virtual Machine.

Procedure

In the command line that is used to run the Java Virtual Machine, enter The IP address of the JVM (local or remote host) and the IP port.
Optional: You can optionally use authentication security data to launch the virtual machine. In this case, you must enter the name of the password file. You can also enter the name of a privilege file if needed.

Example

Parameters used to launch a JVM without security:

java
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9010
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false 
-jar MyapplicationFile.jar

Parameters used to launch a JVM with authentication security:

java
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9010
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=true
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.password.file=jmxremote.password
-Dcom.sun.management.jmxremote.access.file=jmxremote.access (this command line is optional)
-jar MyapplicationFile.jar

Feedback