Starting a resource monitoring Java agent as a service on Linux

To ensure that the resource monitoring Java 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

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.

About this task

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

Procedure

  1. Create a folder on your local hard drive like /opt/RMAgent-linuxservice.
  2. Download the agent .jar file that is available from the Agents page in the resource monitoring service, below the Extend the Resource Monitoring service with agents section and save it to the same directory.
  3. Create a new file /etc/systemd/system/RMAgent-linuxservice.service.
  4. 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
  5. Create another file /opt/RMAgent-linuxservice/RMAgent-linuxservice.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 RTCP_OFFLINE_TOKEN=<offline-token>

ARGS="--serviceUrl=$SERVICE_URL --projectId=$PROJECT_ID --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
    Notes:
    • Replace <service-hostname> by the host name of the host that runs IBM® Rational® Test Automation 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 Java agent starts automatically when the host restarts. The Linux agent is added to the main page of the resource monitoring service in IBM® Rational® Test Automation Server.

What to do next

You can monitor the Linux Performance host source by adding counters. See Monitoring a Linux Performance host.