Skip to content

Agents

Introduction

On-Premise Agent configuration

An Agent is a small Docker container running on a physical machine. It provides the following features:

  • Monitor your system: monitor various parts of your system,
  • Load Generator: start / stop / remove JMeter containers to run your load tests.

The Agents table shows the following information:

Column Description
State Green when connected to the server, else Red
IP IP address of the computer running the agent
Last Update When the agent has been updated for the last time
Provider Provider Name associated to this agent
Region Region Name associated to this agent
Name Agent name
Version Docker version and Operating System
Free Memory The server memory information (total and available for load tests).
Containers Number of Docker containers running on this machine

Info

For best efficiency, always use the same hardware configuration for all your agents.

System Requirements

For an optimal load testing experience, we recommend the following configuration for each on-premise agent:

  • CPU: 4 or more vCPUs (Intel Core i7, Intel Xeon or AMD Ryzen 7 recommended),
  • RAM: 8GB+ RAM (16GB recommended),
  • Disk: 16GB+ free hard-disk space (SSD preferred)
  • Operating system: Ubuntu 18.04LTS, 20.04LTS or greater is recommended. Any Distribution which supports the latest Docker Community Edition. (See Docker Install Docs for more info)
  • Server: both physical servers and virtual machines are supported, (physical servers strongly recommended)
  • Software: Docker must be installed. Docker CE 19.03 or newer is recommended,
  • Network: Have a constant access over HTTPS to https://api.octoperf.com.

Recommendations

The table below gives an overview of the amount of virtual users you can run depending on the instance memory and using the default configuration:

  • 256MB base memory allocated,
  • 10MB per virtual user,
  • 65% of the machine memory dedicated to the load tests. (leave at least 30+% memory available for the system)
  • 5 JMeter containers per host.
Available RAM (MB) Number of virtual users
4096 250
8192 500
16384 1000

Depending on the complexity of your scripts, your mileage may vary. Make sure to test a single host capability before scaling them.

Warning

Physical servers are strongly recommended over virtual machines (much more powerful). You can use multiple machines to simulate higher loads.

Info

We suggest to use no more than 70% of available RAM to prevent any performance issue. Some memory must be left for the operating system and filesystem cache.

Info

We recommend to use medium (8Go) to large (16Go) sized machines instead of big ones as JMeter may not behave correctly with very high memory allocation.

Setup

The following procedure explains how to launch an on-premise load generator:

  1. Create an On-Premise Provider with a region on our platform, and select it,
  2. In Agents table, click on Create Agent button,
  3. Select the Region where the agent will be running,
  4. Select the Operating System (Windows or Linux),
  5. Follow the instructions related to the OS.

Warning

The generated command should be used only once. It uniquely identifies the agent.

Warning

Only a single agent per host must be launched. Otherwise, you may experience issues . (auto-upgrade failure, race condition during test launch)

Windows installation

Host install Windows

Host installation on Windows requires Vagrant, a free and open-source software for creating and configuring virtual development environments. It can be considered a wrapper around virtualization software like VirtualBox.

So you need to download and install both software:

  1. Click on the Download VirtualBox button,
  2. Download and install VirtualBox for your Operating System,
  3. Click on the Download Vagrant button,
  4. Select you Operating System (you may also use Vagrant on Linux/Mac),
  5. Download and install Vagrant,
  6. Download the Vagrantfile (it is generated for the selected Provider and Region name, so you must re-download it to install an agent for another Provider / Region),
  7. Execute the command vagrant up in the folder that contains the downloaded Vagrantfile.

The Host should appear in the list in a couple of minutes.

Linux installation

Host install Linux

Host installation on Linux requires Docker. So the first command line installs it - you can skip it if you already have docker on your Linux injector.

The second command line installs the on-premise agent.

  1. Click on the Copy to Clipboard button at the right of the wget command,
  2. Paste it on your terminal to install Docker,
  3. Click on the Copy to Clipboard button at the right of the command. It should look like (do not actually use this one): sudo docker run -d -restart=unless-stopped --name flawed_gentleman -v /var/run/docker.sock:/var/run/docker.sock -e AGENT_TOKEN='...' -e SERVER_URL='https://api.octoperf.com' octoperf/docker-agent:...
  4. Execute the command on the target computer.

The Agent should appear in the list in a couple of minutes.

Configuration

The agent can be configured using environement variables. You can specify an environement variable within the agent docker command using --env or -e parameter. See Docker Run for more information.

The agent supports the following environment variables:

  • AGENT_TOKEN: required. unique token generated by the server, used by the agent to authenticate itself when registering on the server,
  • SERVER_URL: required. Location of the OctoPerf server,
  • octoperf.auto-update: optional. Default to true. Whenever the agent should upgrade itself when a new version is available.

The agent has the following volume mappings:

  • /var/run/docker.sock:/var/run/docker.sock: optional. Gives access to the docker service on the host machine. It's used to start / stop JMeter containers on the host.

Info

The docker.sock volume mapping can be safely removed when the agent is being used for monitoring only.

Warning

The agent must be upgraded manually when the docker.sock volume mapping is not present.

Warning

The agent upgrade may fail unpredictably when several agents are running on the same machine.

Agent Containers

Agent Containers

By clicking on the magnifier next to an agent, the Inspect Agent panel appears. It provides various information including:

  • Agent Information: docker version, operating system, name, last time the agent has been seen etc,
  • Containers Table: displays the containers currently running on this machine.

When selecting a container, container logs are displayed. Those information are mostly provided for debugging purpose.

Firewalls

Backend servers are usually protected behind firewalls to protect them from outer attacks. The agent doesn't require any port opening on firewall: it performs only outgoing HTTPS requests to OctoPerf.

When using:

  • OctoPerf Saas: Firewall outgoing rules must allow the agent to send http requests to https://api.octoperf.com,
  • OctoPerf Enterprise Edition: it depends if a Firewall is placed between your OctoPerf server and your agents.

Proxy

If a direct internet access is not an option, note that it is possible to direct all traffic from docker through a proxy. The procedure is detailed in docker documentation.

Warning

The computer running OctoPerf agent must have a direct access to the application under test. Make sure the proxy is only required to access internet, not the application.

The Agent itself can be configured to use a proxy to communicate with OctoPerf server (https://api.octoperf.com when using OctoPerf Saas) via environment properties when running the agent. The agent is a Java Program

  • -e HTTP_PROXY='hostname': the host name of the proxy server (HTTP),
  • -e HTTPS_PROXY='hostname': the host name of the proxy server (HTTPS),
  • -e NO_PROXY='': a list of hosts that should be reached directly, bypassing the proxy.

If your proxy is SSL-Secured, use https instead of http. For a more complete documentation, see Configuring Proxies documentation.

Stop and Removal

To stop an agent on Linux:

  • Connect on the machine running the container through a Terminal (Linux);
  • Find the container within the list of running containers by running docker ps command,
  • Copy the containerId and run the command docker stop containerId.

The agent should be marked as DOWN within a few minutes.

Info

Agents down for a while (>= 1 Hour) are automatically removed.

Info

Restarting a removed agent will make it reappear on the server again in UP state.

Troubleshooting

I'm using podman instead of docker

In that case there's a few changes you have to make.

Edit the command line

Make it look like this:

Command line

sudo podman run -d --restart=unless-stopped --name XXXX -v /var/run/podman/podman.sock:/var/run/docker.sock -e AGENT_TOKEN='XXXX' -e SERVER_URL='XXXX' docker.io/octoperf/docker-agent:XX.XX.X

sudo docker run -d --restart=unless-stopped --name XXXX -v /var/run/docker.sock:/var/run/docker.sock -e AGENT_TOKEN='XXXX' -e SERVER_URL='XXXX' octoperf/docker-agent:XX.XX.X

Warning

Make sure to replace all the XXXX with values from the docker command line you got from OctoPerf's UI.

Custom registry

Add docker.io as a custom registry in the provider:

podman-registry

Known issues

My agent does not appear in the agents list.

Make sure you have successfully installed Docker and launched the agent on the machine. You can inspect the Docker container logs by using the command docker logs -f <container id>. Feel free to contact us if you still experience some issues.

The vagrant up command hangs on Windows 7.

This is a known vagrant issue: https://github.com/hashicorp/vagrant/issues/8783.

You simply need to download and install the latest PowerShell on windows 7.

The agent upgrade somehow failed. How can I restart a new agent?

Delete the existing agent by running the following commands: docker ps -a | grep docker-agent docker rm -f <containerId>

Then proceed to re-install it.

My Agent stays in DOWN state. How can I find the root cause?

Display the Agent Logs

Connect via a linux terminal on the host machine and inspect the containers using the command docker ps -a | grep docker-agent. Find the monitoring-agent container and copy its id. Then run docker logs <containerId> where is the id of the container.

The agent logs should show you if it's a connectivity issue (no internet connection?) or something else. Contact our support team in case you are unable to find out.

Switching Logs to Debug

In case the default logs do not give enough information you may start a new agent with this environment variable added: -e JAVA_OPTS="-Dorg.slf4j.simpleLogger.defaultLogLevel=debug".

This will activate DEBUG logs and may help you find out what is going on.

Try to Connect to the REST API

You should be able to retrieve the list of Workspaces from the machine hosting the OctoPerf docker agent. Calling the REST API ensures that the Agent is able to communicate with the backend.

Run the following command:

curl --header "Authorization: Bearer API_KEY" -v https://api.octoperf.com/workspaces/member-of

You API key can be found in the OctoPerf application profile section.

You may also run this command from the inside of the agent Docker container: 

docker exec -it <containerId> /bin/bash

Once connected to the container shell:

apt-get -qq update
apt-get -qq -y install curl
curl --header "Authorization: Bearer API_KEY" -v https://api.octoperf.com/workspaces/member-of