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.