Apache JMeter Cheatsheet¶

Installation¶

Platform	Command
Ubuntu/Debian	`sudo apt update && sudo apt install jmeter`
Ubuntu (Snap)	`sudo snap install jmeter`
macOS (Homebrew)	`brew install jmeter`
Windows (Chocolatey)	`choco install jmeter`
Binary (Linux/macOS)	`wget https://dlcdn.apache.org//jmeter/binaries/apache-jmeter-5.6.3.tgz && tar -xzf apache-jmeter-5.6.3.tgz`
Docker	`docker pull justb4/jmeter:latest`
Prerequisites	Java JDK 8+ required: `java -version`

Post-Installation Setup¶

# Add JMeter to PATH (Linux/macOS)
export JMETER_HOME=/opt/apache-jmeter-5.6.3
export PATH=$PATH:$JMETER_HOME/bin

# Verify installation
jmeter --version

# Increase heap size (add to ~/.bashrc or jmeter startup script)
export JVM_ARGS="-Xms1g -Xmx4g"

Basic Commands¶

Command	Description
`jmeter`	Launch JMeter GUI
`jmeter -t test-plan.jmx`	Open specific test plan in GUI
`jmeter -n -t test.jmx -l results.jtl`	Run test in non-GUI mode with results
`jmeter -n -t test.jmx -l results.jtl -e -o report/`	Run test and generate HTML dashboard
`jmeter --version` or `jmeter -v`	Display JMeter version
`jmeter --help` or `jmeter -h`	Show help and available options
`jmeter -?`	List all available properties
`jmeter -n -t test.jmx -j jmeter.log`	Run test with custom log file
`jmeter -g results.jtl -o dashboard/`	Generate HTML report from existing results
`jmeter -p custom.properties`	Launch with custom properties file
`jmeter -Xmx4g`	Launch with increased heap size (4GB)
`jmeter-server`	Start JMeter in server mode for distributed testing
`jmeter -n -t test.jmx -l results.csv`	Run test and save results as CSV
`jmeter -n -t test.jmx -l results.xml`	Run test and save results as XML
`jmeter -Jusers=100`	Override property value at runtime

Advanced Usage¶

Command	Description
`jmeter -n -t test.jmx -r`	Run test on all remote servers
`jmeter -n -t test.jmx -R server1:1099,server2:1099`	Run test on specific remote servers
`jmeter -n -t test.jmx -Gusers=100 -Grampup=60`	Set global properties for remote servers
`jmeter -n -t test.jmx -r -X`	Run distributed test and exit remote servers after
`jmeter -n -t test.jmx -q env.properties -q users.properties`	Use multiple property files
`jmeter -H proxy.example.com -P 8080`	Run with HTTP proxy
`jmeter -H proxy.com -P 8080 -u username -a password`	Run with authenticated proxy
`jmeter -Lorg.apache.jmeter=DEBUG`	Set log level to DEBUG
`jmeter -Lorg.apache.jmeter.protocol.http=DEBUG`	Set log level for specific package
`jmeter-server -Djava.rmi.server.hostname=192.168.1.100`	Start server with specific hostname
`jmeter-server -Dserver_port=1099`	Start server on custom port
`jmeter -n -t test.jmx -Jsummariser.interval=30`	Set summary interval to 30 seconds
`jmeter -n -t test.jmx -Jjmeter.save.saveservice.output_format=xml`	Force XML output format
`jmeter -n -t test.jmx -Jjmeter.save.saveservice.response_data=true`	Include response data in results
`jmeter -XX:+UseG1GC -n -t test.jmx`	Run with G1 garbage collector
`jmeter -Dcom.sun.management.jmxremote -n -t test.jmx`	Enable JMX monitoring
`jmeter -Dhttp.keepAlive=false -n -t test.jmx`	Disable HTTP keep-alive
`jmeter -g results.jtl -o dashboard/ -f`	Force overwrite existing dashboard
`jmeter -N "localhost\|*.internal.com"`	Set non-proxy hosts
`PluginsManagerCMD.sh install jpgc-casutg,jpgc-synthesis`	Install JMeter plugins via CLI

Configuration¶

JMeter Properties File (`jmeter.properties`)¶

# Thread and ramp-up settings
jmeter.threads=100
jmeter.rampup=60

# Remote server configuration
remote_hosts=server1:1099,server2:1099,server3:1099

# Result file configuration
jmeter.save.saveservice.output_format=csv
jmeter.save.saveservice.response_data=false
jmeter.save.saveservice.samplerData=false
jmeter.save.saveservice.requestHeaders=false
jmeter.save.saveservice.url=true
jmeter.save.saveservice.responseHeaders=false

# HTTP settings
httpclient.reset_state_on_thread_group_iteration=true
http.keepAlive=true
http.connection.timeout=30000
http.socket.timeout=120000

# Summariser interval (seconds)
summariser.interval=30

# Log level
log_level.jmeter=INFO
log_level.jmeter.engine=DEBUG

User Properties File (`user.properties`)¶

# Custom variables
baseurl=https://example.com
users=100
rampup=60
duration=300

# Environment-specific settings
env=production
api_key=your_api_key_here

System Properties¶

# Set system properties via command line
jmeter -Dhttp.proxyHost=proxy.example.com \
       -Dhttp.proxyPort=8080 \
       -Dhttps.proxyHost=proxy.example.com \
       -Dhttps.proxyPort=8080 \
       -n -t test.jmx

JVM Configuration (`jmeter` script)¶

# Edit JMETER_HOME/bin/jmeter or set environment variable
export HEAP="-Xms1g -Xmx4g -XX:MaxMetaspaceSize=256m"
export GC_ALGO="-XX:+UseG1GC -XX:MaxGCPauseMillis=100 -XX:G1ReservePercent=20"
export JVM_ARGS="$HEAP $GC_ALGO"

Distributed Testing Configuration¶

# In jmeter.properties on controller machine
remote_hosts=192.168.1.101:1099,192.168.1.102:1099,192.168.1.103:1099

# Server RMI configuration
server.rmi.ssl.disable=true
server.rmi.localport=4000
server_port=1099

# On remote server machines
java.rmi.server.hostname=192.168.1.101

Common Use Cases¶

Use Case 1: Basic Load Test with HTML Report¶

# Run load test with 100 users, 60s ramp-up, generate HTML report
jmeter -n -t load-test.jmx \
       -Jusers=100 \
       -Jrampup=60 \
       -Jduration=300 \
       -l results/results.jtl \
       -e -o results/dashboard/ \
       -j results/jmeter.log

# View the report
open results/dashboard/index.html  # macOS
xdg-open results/dashboard/index.html  # Linux

Use Case 2: Distributed Load Test Across Multiple Servers¶

# Step 1: Start JMeter servers on remote machines
# On server1 (192.168.1.101):
jmeter-server -Djava.rmi.server.hostname=192.168.1.101

# On server2 (192.168.1.102):
jmeter-server -Djava.rmi.server.hostname=192.168.1.102

# Step 2: Run distributed test from controller
jmeter -n -t distributed-test.jmx \
       -R 192.168.1.101:1099,192.168.1.102:1099 \
       -Gusers=500 \
       -Grampup=120 \
       -l distributed-results.jtl \
       -e -o distributed-report/

# Step 3: Shutdown remote servers
jmeter -n -t distributed-test.jmx -R 192.168.1.101:1099,192.168.1.102:1099 -X

Use Case 3: API Performance Testing with Multiple Environments¶

# Create environment-specific property files
# dev.properties:
echo "baseurl=https://dev-api.example.com" > dev.properties
echo "api_key=dev_key_123" >> dev.properties

# prod.properties:
echo "baseurl=https://api.example.com" > prod.properties
echo "api_key=prod_key_456" >> prod.properties

# Run test against dev environment
jmeter -n -t api-test.jmx \
       -q dev.properties \
       -Jusers=50 \
       -l dev-results.jtl \
       -e -o dev-report/

# Run test against production environment
jmeter -n -t api-test.jmx \
       -q prod.properties \
       -Jusers=200 \
       -l prod-results.jtl \
       -e -o prod-report/

Use Case 4: CI/CD Integration (Jenkins/GitLab)¶

#!/bin/bash
# performance-test.sh - CI/CD pipeline script

# Set variables
TEST_PLAN="test-plans/load-test.jmx"
RESULTS_DIR="results/$(date +%Y%m%d_%H%M%S)"
USERS=${USERS:-100}
DURATION=${DURATION:-300}

# Create results directory
mkdir -p $RESULTS_DIR

# Run JMeter test
jmeter -n -t $TEST_PLAN \
       -Jusers=$USERS \
       -Jduration=$DURATION \
       -l $RESULTS_DIR/results.jtl \
       -e -o $RESULTS_DIR/dashboard/ \
       -j $RESULTS_DIR/jmeter.log

# Check for errors (exit code)
if [ $? -eq 0 ]; then
    echo "Test completed successfully"

    # Archive results
    tar -czf $RESULTS_DIR.tar.gz $RESULTS_DIR

    # Optional: Upload to artifact storage
    # aws s3 cp $RESULTS_DIR.tar.gz s3://bucket/results/
else
    echo "Test failed with errors"
    exit 1
fi

Use Case 5: Database Performance Testing¶

# Test database performance with parameterized queries
jmeter -n -t database-test.jmx \
       -Jdb.host=db.example.com \
       -Jdb.port=5432 \
       -Jdb.name=testdb \
       -Jdb.user=testuser \
       -Jdb.password=testpass \
       -Jthreads=50 \
       -Jrampup=30 \
       -l db-results.jtl \
       -e -o db-report/

# Generate report from existing results
jmeter -g db-results.jtl -o db-report-regenerated/

Best Practices¶

Always use non-GUI mode for actual testing: GUI mode consumes significant resources and affects test accuracy. Use jmeter -n for all performance tests.
Allocate sufficient heap memory: Set JVM heap size to at least 25% of available RAM. For large tests: export JVM_ARGS="-Xms2g -Xmx4g -XX:+UseG1GC"
Use CSV format for result files: CSV format is more efficient than XML. Disable unnecessary data collection to reduce overhead: jmeter.save.saveservice.response_data=false
Implement proper ramp-up periods: Avoid starting all threads simultaneously. Use gradual ramp-up (typically 10-20% of test duration) to simulate realistic load patterns.
Leverage distributed testing for high loads: Single machine limitations can skew results. Use multiple JMeter servers for tests exceeding 500-1000 threads.
Parameterize test data: Use CSV Data Set Config or variables instead of hardcoded values. This enables easy test configuration and environment switching.
Monitor system resources during tests: Track CPU, memory, network, and disk I/O on both JMeter machines and target systems. High resource usage on JMeter indicates bottlenecks in test execution.
Version control test plans: Store .jmx files and property files in Git. Use meaningful commit messages and tag releases for reproducibility.
Implement proper correlation and assertions: Extract dynamic values (tokens, session IDs) and validate responses. Don't just measure speed—verify correctness.
Clean up between test runs: Clear results directories and logs. Reset application state when needed to ensure consistent test conditions.

Troubleshooting¶

Issue	Solution
OutOfMemoryError during test	Increase heap size: `export JVM_ARGS="-Xms2g -Xmx4g"` or reduce threads/disable response data saving
Connection refused on remote servers	Check firewall rules for ports 1099 and 4000. Verify `java.rmi.server.hostname` is set correctly on server
Test results show 100% errors	Verify target URL is accessible, check proxy settings, review `jmeter.log` for detailed error messages
GUI freezes during large tests	Never run large tests in GUI mode. Use non-GUI: `jmeter -n -t test.jmx -l results.jtl`
Inconsistent results between runs	Ensure proper ramp-up, clear cache/cookies between runs, verify network stability, check target system load
Cannot generate HTML report	Verify results file format is compatible (CSV/JTL), ensure output directory is empty or use `-f` flag to force overwrite
Remote servers not starting	Check Java version compatibility (JDK 8+), verify RMI registry port is available, review `jmeter-server.log`
SSL/TLS certificate errors	Add certificate to Java keystore or disable validation: `jmeter -Jhttps.default.protocol=TLSv1.2`
Slow test execution	Disable listeners in non-GUI mode, reduce assertion complexity, optimize regular expressions, use efficient extractors
"Non HTTP response code: java.net.SocketException"	Increase timeout values, check connection pool settings, verify target system capacity, reduce thread count
Distributed test results incomplete	Ensure all servers have same test plan version, check network connectivity, verify clock synchronization across servers
High CPU on JMeter machine	Reduce thread count, disable unnecessary processors/listeners, use simpler samplers, consider distributed testing
Cannot install plugins	Download Plugins Manager JAR manually to `lib/ext/`, ensure internet connectivity, check proxy settings
Results file corrupted or empty	Ensure sufficient disk space, check file permissions, verify JMeter process completed successfully
"Address already in use" error	Change server port: `jmeter-server -Dserver_port=1100`, kill existing JMeter processes, wait for port release

Quick Reference: Command Line Options¶

Option	Description	Example
`-n`	Non-GUI mode	`jmeter -n -t test.jmx`
`-t`	Test plan file	`jmeter -t mytest.jmx`
`-l`	Results log file	`jmeter -n -t test.jmx -l results.jtl`
`-j`	JMeter log file	`jmeter -n -t test.jmx -j jmeter.log`
`-r`	Run on all remote servers	`jmeter -n -t test.jmx -r`
`-R`	Run on specific servers	`jmeter -n -t test.jmx -R server1,server2`
`-g`	Generate report from file	`jmeter -g results.jtl -o report/`
`-e`	Generate report after test	`jmeter -n -t test.jmx -l results.jtl -e -o report/`
`-o`	Output folder for report	`jmeter -g results.jtl -o dashboard/`
`-H`	Proxy host	`jmeter -H proxy.com -P 8080`
`-P`	Proxy port	`jmeter -H proxy.com -P 8080`
`-u`	Proxy username	`jmeter -H proxy.com -P 8080 -u user`
`-a`	Proxy password	`jmeter -H proxy.com -P 8080 -a pass`
`-J`	Define JMeter property	`jmeter -Jusers=100 -Jrampup=60`
`-G`	Define global property	`jmeter -Gusers=100` (for remote servers)
`-D`	Define system property	`jmeter -Dhttp.proxyHost=proxy.com`
`-L`	Set log level	`jmeter -Lorg.apache.jmeter=DEBUG`
`-p`	Property file	`jmeter -p custom.properties`
`-q`	Additional property file	`jmeter -q env.properties`
`-X`	Exit remote servers	`jmeter -n -t test.jmx -r -X`
`-f`	Force delete output folder	`jmeter -g results.jtl -o report/ -f`

Apache JMeter Cheatsheet¶

Installation¶

Post-Installation Setup¶

Basic Commands¶

Advanced Usage¶

Configuration¶

JMeter Properties File (jmeter.properties)¶

User Properties File (user.properties)¶

System Properties¶

JVM Configuration (jmeter script)¶

Distributed Testing Configuration¶

Common Use Cases¶

Use Case 1: Basic Load Test with HTML Report¶

Use Case 2: Distributed Load Test Across Multiple Servers¶

Use Case 3: API Performance Testing with Multiple Environments¶

Use Case 4: CI/CD Integration (Jenkins/GitLab)¶

Use Case 5: Database Performance Testing¶

Best Practices¶

Troubleshooting¶

Quick Reference: Command Line Options¶

JMeter Properties File (`jmeter.properties`)¶

User Properties File (`user.properties`)¶

JVM Configuration (`jmeter` script)¶