Skip to content

Configuration Files

Most Load Tester settings are controlled through Window → Preferences (see Settings Reference). Configuration files handle the exceptions: settings that live outside the preferences UI, engine tuning, debug logging, and edge cases like manual cookie overrides or custom hostname resolution.

Most users will never touch these files. When you do, it's usually because support asked you to enable debug logging, or because your network topology is complicated enough to require manual engine configuration.

File Locations

Configuration files live in three places depending on what they control.

Location Contains Path
Workspace User-specific config (debug logging, cookie overrides, hostname mapping) ~/WebPerformance7/ (macOS/Linux) or C:\Users\<username>\WebPerformance7\ (Windows)
Application directory Workspace location setting Where you installed Load Tester
Engine directory Load engine and server agent tuning Where the engine or agent is installed

Finding Your Workspace

If you're not sure where your workspace is, check Window → Preferences → General → Startup and Shutdown. Or look at config.ini in your application's install directory for the osgi.instance.area setting.

Workspace Configuration Files

These files live under your workspace directory. Create them manually if they don't exist; Load Tester checks for them at startup.

diagnostic.properties

Location: <workspace>/config/diagnostic.properties

Enables debug logging for troubleshooting. Each flag controls a category of diagnostic output that gets written to the diagnostic log.

# Enable debug output for specific subsystems
# Uncomment (remove #) to activate, restart Load Tester

# HTTP session and cookie tracking
#HTTP.transport=true

# ASM field detection and correlation
#ASM.debug=true

# AWS cloud engine state changes
#AWS.engineStates=true

# CLI headless execution
#Debug.CLI=true

# Timestamps in debug output
#Debug.show_time=true

# Recording proxy and Chrome extension
#Recording.debug=true

When to edit: Only when support asks you to enable specific debug flags. Enable only the flags you need, since verbose logging can slow performance and generate large log files.

Takes effect: After restarting Load Tester.

cookies.cfg

Location: <workspace>/config/cookies.cfg (create if it doesn't exist)

Manual cookie override rules for browser-specific cookies that JavaScript sets during recording but that Load Tester can't extract from HTTP responses. This is a rare edge case; ASM handles the vast majority of cookies automatically.

# Format: one rule per line
# cookie_name = value ; condition
#
# Example: Force a specific analytics cookie value
# _ga = GA1.2.123456789.1234567890 ; domain=.example.com

When to edit: Recording succeeds but replay fails with 401/403 errors, and you've confirmed that JavaScript sets a required cookie that never appears in any HTTP response. Try ASM correlation first. This file is the last resort.

hosts.txt

Location: <workspace>/config/hosts.txt (create if it doesn't exist)

Custom hostname-to-IP mapping, similar to the system hosts file but specific to Load Tester. Useful for redirecting traffic to test servers without modifying system-wide DNS.

# Format: hostname IP
# One entry per line

staging.example.com 10.1.1.50
api-test.example.com 10.1.1.51

# Multiple IPs for round-robin (load engines distribute across them)
app.example.com 10.1.1.50 10.1.1.51 10.1.1.52

Resolution order: Load Tester checks hosts.txt first, then the system hosts file, then DNS.

When to edit: You need to redirect test traffic to staging servers, bypass DNS for internal hostnames, or distribute load engine traffic across multiple server IPs.

Application Configuration

config.ini

Location: <install>/config/config.ini

Controls where Load Tester stores its workspace (settings, preferences, and test data). The default workspace is ~/WebPerformance7/ on all platforms.

# Default: auto-detect (uses ~/WebPerformance7/)
osgi.instance.area=@noDefault

# Use a subfolder of the install directory
# osgi.instance.area=workspace

# Use a custom absolute path
# osgi.instance.area=C:\\Users\\username\\MyWorkspace

# Use a path relative to user home
# osgi.instance.area=@user.home/CustomWorkspace

Windows Path Syntax

Backslashes must be doubled in config.ini: C:\\Users\\username\\Path. A single backslash is treated as an escape character.

When to edit: Moving the workspace to a network drive, setting up separate workspaces for different projects, or migrating from a previous version. See Workspace Management for the full migration workflow.

Load Engine Configuration

These files live in the load engine installation directory on each engine machine (local or cloud).

system.properties (Load Engine)

Location: <engine-install>/system.properties

Controls network binding and capacity settings for load engines.

Property Description Default
EngineRMIAddress IP address the engine listens on (use when server has multiple NICs) Auto-detect
RmiRegistryPort Port for RMI registry 1099
RmiEnginePort Port for engine communication Any available
EngineUserCapacity Maximum virtual users this engine can run 5000
StartingRemoteEngineUserCapacity Initial VU allocation when ramping up 1000 
# Example: Engine behind NAT, bind to internal IP, fixed ports for firewall
EngineRMIAddress=10.0.1.100
RmiRegistryPort=1099
RmiEnginePort=1100
EngineUserCapacity=5000

When to edit: The engine is behind a firewall or NAT (fixed ports needed for firewall rules), the server has multiple network interfaces, or you need to increase VU capacity beyond the default.

system.properties (Server Monitoring Agent)

Location: <agent-install>/system.properties

Controls network binding for the server monitoring agent.

Property Description Default
RmiAgentAddress IP address the agent listens on Auto-detect
RmiRegistryPort Port for RMI registry 1099
RmiAgentPort Port for agent communication 1100

When to edit: Multi-NIC servers where auto-detection picks the wrong interface, or firewall rules require specific ports.

.lax Files (JVM Configuration)

Location: <engine-install>/Load Engine.lax or <agent-install>/Server Monitor Agent.lax

Controls JVM settings for load engines and server monitoring agents. You'll only edit these for two reasons: memory allocation and NAT hostname configuration.

Setting Purpose Example
-Xmx<size> Maximum heap memory -Xmx4g (4 GB)
-Xms<size> Initial heap memory -Xms1g (1 GB)
-Djava.rmi.server.hostname=<host> Public hostname for NAT traversal -Djava.rmi.server.hostname=engine.example.com

Add JVM options to the lax.nl.java.option.additional line in the .lax file.

When to edit: Out-of-memory errors during large load tests (increase -Xmx), or the engine is behind NAT and the controller can't connect back to it (set the public hostname).

Cloud Engines

Cloud-provisioned engines are configured automatically. You only need to edit .lax files on manually installed engines.

Log Files

These are generated automatically. You never edit them, but you need to know where they are when something goes wrong.

File Location Purpose
diagnostic.log <workspace>/.metadata/.plugins/com.webperformanceinc.util/diagnostic.log Primary diagnostic log. Always include when contacting support.
.metadata/.log <workspace>/.metadata/.log Eclipse platform crash log. Check when Load Tester fails to start.

See Getting Support for how to gather and send diagnostic information.

Workspace Directory Structure

For reference, here's what your workspace contains. Files marked (generated) are created automatically and should not be copied when migrating to a new machine.

~/WebPerformance7/
├── config/
│   ├── diagnostic.properties        # Debug logging flags
│   ├── cookies.cfg                  # Cookie overrides (optional, create manually)
│   └── hosts.txt                    # Hostname mapping (optional, create manually)
├── .metadata/
│   ├── .log                         # Eclipse crash log (generated)
│   └── .plugins/
│       └── com.webperformanceinc.util/
│           ├── diagnostic.log       # Primary diagnostic log (generated)
│           ├── validation/          # Custom validation rules
│           ├── asm/                 # ASM detection rules
│           ├── recording/           # Recording preferences
│           ├── fields/              # Field defaults
│           ├── browsers.cfg         # Browser detection (generated, system-specific)
│           ├── SavedBrowser.cfg     # Browser config cache (generated)
│           └── certificates/        # SSL certificates (generated, system-specific)
└── .webperformance/                 # Internal state (generated)

Migration: Don't Copy Generated Files

When migrating to a new machine, copy config/, validation/, asm/, recording/, and fields/. Don't copy browsers.cfg, SavedBrowser.cfg, or certificates/ since these are system-specific and will be regenerated. See Workspace Management for the complete migration procedure.