Skip to content

Server Monitoring Agent

The Server Monitoring Agent is a lightweight application that runs on your servers and provides detailed performance metrics during load tests. It won't modify your registry, install services outside its own directory, or require special permissions in most cases. It's designed for production systems, and it stays in its lane.

The biggest reason to use it (or CloudWatch Monitoring on AWS) is that the metrics flow directly into the load-test result alongside response times, errors, and throughput. That co-location is what lets the AI assistant do deep root-cause analysis: it can correlate a 14:23:15 response-time spike against a CPU saturation that happened on a specific server two seconds earlier, name the cause, and explain the chain. Without server data in the same dataset, AI analysis stops at "client-side symptoms" and you do the rest of the correlation by hand. See Why This Matters for AI Analysis for the longer version of this argument.

The agent works in two modes:

  • Basic mode: CPU and memory only. Available at every license tier, including Free.
  • Advanced mode: Hundreds of metrics including database connections, disk I/O, thread pools, garbage collection, and platform-specific counters. Available in the Pro tier. See the purchase configure page for current tier details.

This guide walks you through installing, running, and configuring the agent.

What You're Installing

The agent is a Java application that collects performance data while your load test runs. It listens on port 1099 (configurable) and auto-detects on your local network so the Load Tester can find it automatically.

Permissions: In most cases, the agent doesn't need special permissions: - Linux: No root required - Windows: No administrator required

The agent responds to any client that connects to its ports, so if you're in a locked-down environment, use firewall rules to restrict access or collect stats files manually.

Installing the Agent

Step 1: Download the Installer

  1. Go to www.webperformance.com/download/
  2. Click the green Server Monitor button for Windows 64-bit
  3. Or click Other platforms to see Linux, 32-bit, and other options

Step 2: Run the Installer

Windows: Run the installer. A GUI will walk you through the installation. Default location is C:\Program Files\Web Performance\Server Monitor Agent\.

Linux: 

chmod +x ServerAgent_Linux_*.bin
./ServerAgent_Linux_*.bin

The installer will prompt you for the installation directory. Default is ~/Web_Performance_Server_Monitor_Agent/.

Important: The agent is safe to install on production systems. It doesn't modify the registry (Windows) or system files. Everything installs in its own directory.

Silent Installation (for automation)

If you're deploying to multiple servers, use silent mode:

./ServerAgent_Linux_*.bin -i silent

This installs with default settings. For custom settings, create a file named installer.properties in the same directory as the installer:

INSTALLER_UI=silent
USER_INSTALL_DIR=~/Web_Performance_Server_Monitor_Agent
USER_SHORTCUTS=~

Then run the installer, and it'll use your custom settings.

Upgrading an Existing Agent

If you have an older agent already installed:

  1. Open the Servers View in Load Tester
  2. Select the server running the old agent
  3. Click Upgrade

The Load Tester will push the new version to the agent automatically.

Running the Agent

Windows

  1. Open the Start menu → Web Performance Server Monitor Agent → Server Monitor Agent
  2. A console window opens showing the agent status

You'll see output like: 

Web Performance Server Monitoring Agent version 7.0.xxx now monitoring.
Agent listening on port 1099.

To stop the agent, type quit in the console.

Linux

  1. Navigate to your installation directory
  2. Run the start script:
cd ~/Web_Performance_Server_Monitor_Agent/
./Server_Monitor_Agent

The agent runs as a console application. You'll see: 

Web Performance Server Monitoring Agent version 7.0.xxx now monitoring.
Using hostname override: 192.168.10.147
Agent listening on port 1099.

Critical: If you're SSH'd into the server, run the agent in screen or a similar utility. The agent is not a daemon. It will die the moment your SSH session times out.

To run in screen: 

screen -S wpagent
cd ~/Web_Performance_Server_Monitor_Agent/
./Server_Monitor_Agent
# Press Ctrl+A, then D to detach

To reconnect later: 

screen -r wpagent

Auto-Detection and Configuration

When the agent starts, it broadcasts its presence on the local network via multicast. If your Load Tester controller is on the same network, the agent should appear automatically in the Servers View.

If it doesn't auto-detect (multicast blocked, different subnet, firewall), manually add it:

  1. Open the Servers View
  2. Click Add...
  3. Select Web Performance Server Monitor Agent
  4. Enter the IP address or hostname of the server
  5. Use port 1099 (default) unless you changed it
  6. Click OK

The Load Tester will verify the connection. If successful, you're done.

Choosing Basic vs. Advanced Mode

When you add an agent, it defaults to advanced mode (detailed metrics). If you don't have an Advanced Server Monitoring license, switch to basic mode:

  1. In the Servers View, right-click the agent
  2. Select Set to Basic Mode

Basic mode covers CPU and memory and is available at every license tier. Advanced mode covers hundreds of additional metrics and is available in the Pro tier.

See: Metrics & Counters for the full list of available metrics in advanced mode.

Running as a Background Process (Linux)

If you want the agent to run as a background process (survives SSH disconnects, starts on boot), use the provided script.

Start in Background

cd ~/Web_Performance_Server_Monitor_Agent/
./Start_Server_Monitor_In_Background

This launches the agent in a screen session named WPASA.

Auto-Start on Boot

Add this line to /etc/rc.local:

/home/[USER]/Web_Performance_Server_Monitor_Agent/Start_Server_Monitor_In_Background

Replace [USER] with the appropriate username.

Or start remotely via SSH:

ssh [USER]@yourserver.com './Web_Performance_Server_Monitor_Agent/Start_Server_Monitor_In_Background'

Connect to a Running Agent

If the agent is running in the background, connect to its screen session:

screen -Dr WPASA

To list all screen sessions:

screen -ls

Collecting Stats Files Manually (Firewall Workaround)

If you can't open firewall ports (1099 and 1100) or prefer not to, you can collect stats files manually and load them after the test.

Process:

  1. Start the agent on the server before your load test

  2. On the agent console, type: 

    start-log --sample-period=10 --name=my-test
    (Use the same sample period as your load test, typically 10 seconds)

  3. Run your load test (the agent collects data locally, no connection needed)

  4. After the test, on the agent console: 

    stop-log
quit

  5. Collect the stats file from:

  6. Linux: ~/.webperformance/AgentLogs/
  7. Windows: %USERPROFILE%\.webperformance\AgentLogs\

You'll see a file like 2026_02_10_143022_edt_my-test.dat

  1. Load the stats file into Load Tester:
  2. Open your completed load test result
  3. Go to File → Import Server Logs
  4. Select the .dat file

The server metrics will be integrated into your test results as if the agent had been connected in real time.

See: Monitoring Through Firewalls for detailed firewall configuration.

Viewing Collected Data

Once the agent is running and connected during a load test, metrics are automatically recorded. After the test:

In the Load Test Report: 1. Open your test result 2. Navigate to the Servers section 3. You'll see charts and tables showing: - CPU and memory over time - Correlation with client response times - A performance checklist highlighting bottlenecks

In the Metrics View: 1. Use the drop-down to select your server 2. Choose specific metrics (CPU, memory, database connections, etc.) 3. The table shows metric values sampled throughout the test

Agent Commands Reference

When the agent is running, you can type commands at its console:

Frequently Used

Command What It Does
quit Stops the agent (type this before shutting down the server)
commands Lists all available commands
counters Refreshes the list of performance counters the agent is collecting

Performance Logging (for firewall workaround)

Use these when you can't connect to the agent in real time and need to collect stats files manually:

start-log --sample-period=<seconds> --name=<testname>

Starts collecting a performance log that you'll load into Load Tester after the test.

  • --sample-period: How often to sample metrics (should match your load test setting, typically 10)
  • --name: Optional name to identify the log file

Example: 

start-log --sample-period=10 --name=production-test-500vu

After running this command, the agent will print the path to the log file: 

ServerMonitorAgent: prepared for test 2026_02_10_143022_edt_production-test-500vu.
Results will be logged to ~/.webperformance/AgentLogs/2026_02_10_143022_edt_production-test-500vu.dat

Save that path. You'll need it to load the file after the test.

stop-log

Stops logging and closes the current log file. Always run this after your load test finishes so all data is saved to disk.

stop-log --force

Forcefully stops logging even if the log was started remotely by Load Tester. Use this only if the network connection died and Load Tester can't stop the log automatically.

License Management

No longer required. Since version 4.2, you don't need to import licenses onto the agent. Licensing is handled by the Load Tester controller.

Troubleshooting

Agent won't start: - Check that Java is installed (agent requires Java 11 or later) - Verify port 1099 isn't already in use: netstat -an | grep 1099 - Check for permission issues (though agent rarely needs special permissions)

Agent doesn't auto-detect: - Multicast may be blocked on your network - Agent and controller might be on different subnets - Solution: Add the agent manually in Servers View (see "Auto-Detection and Configuration" above)

"Connection refused" during load test: - Verify the agent is running (ps aux | grep ServerMonitor on Linux) - Check firewall rules allow connections to port 1099 - Confirm you're connecting to the correct IP address/hostname

Agent dies when SSH session ends: - You didn't run it in screen or as a background process - Solution: Use ./Start_Server_Monitor_In_Background or run in screen manually

Want to collect stats but can't open firewall ports: - Use manual stats file collection (see "Collecting Stats Files Manually" above) - Start the agent, run start-log command, run test, run stop-log, collect the .dat file

Next Steps

The agent is low-impact and safe for production systems. Start it before your test, let it collect data, and use the metrics to correlate server-side resource usage with client-side performance degradation.