Introduction

The ATS Agent is a Java application which is used by some ATS framework classes to do their job.

As soon as the Agent is up and running it is ready to be used. You do not usually see an evidence of the existence of the ATS Agent in your test code, but when you use some known framework classes they might internally use the Agent.

The ATS Agent is mainly used for:

1. Executing a command on a remote host. For example when the Test Executor needs to perform some command on a remote host file system.
   In such case we call it the Agent
2. Monitoring the state of a remote host.
   In such case we call it the Monitoring Service
3. Loading the Application Under Test with a number of actions from a number of threads( users).
   In such case we call it the Loader

Below is example with landscape with (possible) use of agents. The agent role is put in blue.

Note that on every place agent could be flexible and serve several roles at once. For example monitoring could be started on every Loader or Agent.

Technically ATS Agent is a web application in deployed either standalone (in Jetty Servlet container) or within other Java Web application server. The latest may need extra configuration and here we describe the usual way with standalone Agent.

Installing and starting the ATS agent

This is really easy:

1. Download the ATS Agent zip archive from here. Open the folder with the same version you are already using for other ATS artifacts;
2. Unzip it on the host where you want to run it;
3. Start it by using agent.bat start on Windows or agent.sh start on UNIX-based platforms.

Now you can use it from your tests.

Agent file structure

Following are the folders and files you will find after unzipping the agent archive

• ats-agent
  • actions
    the Agent component JARs containing classes with actions* that can be run remotely
    
  • actions_dependencies
    JARs with classes needed by the actions
  • container
    libraries used to start the Agent web container
  • endorsed
    libraries used instead the ones from your Java distribution
  • webapp
    the Agent web application

• logs

  Agent log files

The folders in bold from the list above are the ones you may need to deal with.

* actions - More about actions and other terminology you may check later in Performance testing part of the documentation. By default agent is bundled with:

• filesystem operation actions. This aids execution of operations on the remote file system like copying files and directories there, getting checksums (MD5), file contents, copying files between agent etc.
• system operation actions. This includes getting remote OS type, getting agent version, system properties and time.

Verify it runs properly

Following you can see some common problems and ways to investigate them

Make sure there are no errors in its console

The usual error is to be unable to find a Java executable. Or maybe you are using a too old Java version.

Another usual error is to complain the port is already taken by another application. Or maybe you've already started the Agent.

Make sure there are no errors in its log file

The Agent log file is called ATSAgentAudit.log and is placed in the logs sub-folder.

In most cases this file will tell you what the Agent is doing when user has called some remote action.

No errors but cannot communicate with the Agent

If see no errors, but cannot communicate with the Agent then you either cannot reach this host( ping command can help you) or you should suspect a firewall preventing the communication on the Agent port.
You can easily check if the communication is possible between Test Executor and Agent by trying to open the following URL in a web browser on Test Executor:
"http://<The Agent IP or host name>:<The Agent port>/agentapp".
On success you will see a message informing the application is running.

Configuring the ATS agent

Run the agent with the help command option (./agent.sh help or agent.bat help) and you will see different options.

You can specify:

• port to use
• Java VM executable
• max memory size

More options will be found in the agent.bat and agent.sh files.

Default port

By default the Agent is running on port 8089. If in your test (code) you do not provide a port value, then 8089 will be used.

System.setProperty( "ats.agent.default.port", "8888" );

Running ATS Agent in a Docker/container environment

There is ready ATS Agent Docker image  which could be used in a container environment. For more details check this page

Running ATS Agent on the local host

Of course the ATS Agent can run on any host, including the local one.

But running the Agent locally does not mean we will use it. For example when using the FileSystemOperations class we will check whether you want to run your command locally or remotely. Only in the latter case we will work with an ATS Agent.

But still, there are cases when you must run it locally. This is when you want to monitor the system resources of the local host and also when you want to use the local host as a Loader.

Running more than one ATS Agent on same host

If you find a good reason to use more than one Agent on same host just make sure you specify different port number for each instance. Otherwise you will be getting "Port already in use" errors.

Start it as a service

Here you can see how to let the Agent start on system start.

Back to parent page

Go to Table of Contents