Starting a resource monitoring Java agent as a service on Windows

To ensure that the resource monitoring Java agent starts by itself when the host is running, you can set up the environment in such a way that the resource monitoring agent can be started as a service.

Before you begin

You must have completed the following tasks:

Installed Java 8 on the host.
Added IBM® Rational® Test Automation Server to the PATH environment variable.
Created an offline token to connect the agent securely with appropriate permissions.
Note: You can create an offline token from the User menu of the resource monitoring page or you can re-use your active offline token. The token expires if it is not used for a month.

To allow remote access to the performance data on Windows 10, you must have considered the following information:

The user name and password are the same on the local and remote servers. Otherwise you must have provided remote server credentials.
The remote user must be a member of the Performance Monitor Users group (start lusrmgr.msc and add the user to this group).
The Remote Registry service must be running on the remote host (start services.msc) and must have verified the Remote Registry status).
File and printer sharing must be enabled on the Network Interface of the remote host that is implied in the communication with the local host.
You must have activated the following Windows Firewall rules so that the remote firewall does not block the access:
- File and Printer Sharing (NB-Name-In)
- File and Printer Sharing (NB-Session-In)
- File and Printer Sharing (*)

Procedure

Download the latest release of winsw.
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.

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

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

Notes:

Replace <service-host> by the host name of the host that runs IBM® Rational® Test Automation Server.
Replace <project-id> which is the number that you find after /projects/ in the browser's URL when you browse to this project.

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

Copy the following content to this new file to upgrade the agent .jar file automatically:

@echo off
for /f "tokens=*" %%a in ('dir /b /od %BASE%\com.ibm.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 that is available from the agents page in the resource monitoring service, under the Extend the Resource Monitoring service with agents section and save it to the same directory.
Enter the following command in the command prompt to create a symbolic link named RMAgent.jar to the agent jar file:
```
mklink RMAgent.jar com.ibm.ibm.rm.agent-<version-and-datetime>.jar
```
Enter the following commands:
```
RMAgent-winservice install
```
```
RMAgent-winservice start
```
Notes:
In the Services Windows application, you can check whether the service is up and running. You can see in the resource monitoring page whether the resource monitoring agent is disconnected or connected.
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. If the Windows service for the agent is not started or if it is not connected to the resource monitoring service, verify the log files.

Results

The Java agent starts as a service on Windows. When the agent is connected to IBM® Rational® Test Automation Server, it is automatically added to the list of resource monitoring sources in IBM® Rational® Test Automation Server.

What to do next

You can monitor the Windows agent by selecting counters. See Monitoring a Windows Performance host.