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.

Prerequisites

OctoPerf On-Premise agents have the following installation requirements:

  • CPU: At least 4 cores, Intel Core I7 or Xeon recommended,
  • RAM: At least 4GB RAM, 8GB recommended,
  • Operating system: Linux, Ubuntu 16.04LTS, 18.04LTS or greater is recommended. Any Distribution which supports the latest Docker versions. (See Docker Install Docs for more info)
  • Server: both physical and virtual machines are supported,
  • Software: Docker must be installed. Docker 17.09CE or newer is recommended.

Warning

RHEL distributions are not supported by Docker. Prefer Ubuntu or CentOS.

Recommendations

The machines used as load generators must:

  • Have a constant access over HTTPS to https://api.octoperf.com:443,
  • Have enough Free RAM Memory (see table below),

You may also use at least quad-cores processor machines, with 10GB free hard-disk space.

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:

  • 128MB allocated to start JMeter,
  • 5MB additional for each virtual user,
  • 70% of the machine memory dedicated to the load tests.
Memory (MB) Number of virtual users
4096 547
8192 1121
16384 2242

Warning

Bare-metal Linux machines are strongly recommended for running the load tests. 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 small (8Go) to medium (16Go) sized machines instead of big ones as JMeter may not behave correctly with very high memory allocation.

Agent 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.

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 sudo docker run -d --privileged --restart=unless-stopped --name flawed_gentleman -v /var/run/docker.sock:/var/run/docker.sock -e AGENT_TOKEN='...' -e SERVER_URL='http://192.168.1.40:8090' octoperf/docker-agent:... command,
  4. Execute the command on the target computer.

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

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 HTTP 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

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?

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.