Once your Test Plan is ready, you can start your Load Test.
The first step is to configure the injectors that will run JMeter, this as for any other Load Testing tool includes:

Correct machine sizing in terms of CPU, memory and network

OS Tuning

Java setup: Ensure you install the latest version of Java supported by JMeter

Increase the Java Heap size. By default JMeter runs with a heap of 1 GB, this might not be enough for your test and depends on your test plan and number of threads you want to run

Once everything is ready, you will use Command-line mode (called Non-GUI mode) to run it for the Load Test.

Don't run load test using GUI mode !

Using Non-GUI mode, you can generate a CSV (or XML) file containing results and have JMeter generate an HTML report at end of Load Test.
JMeter will by default provide a summary of load test while it's running.
You can also have real-time results during your test using Backend Listener.

The easiest way to begin using JMeter is to first
download the latest production release and install it.
The release contains all of the files you need to build and run most types of tests,
e.g. Web (HTTP/HTTPS), FTP, JDBC, LDAP, Java, JUnit and more.

If you want to perform JDBC testing,
then you will, of course, need the appropriate JDBC driver from your vendor. JMeter does not come with
any JDBC drivers.

JMeter includes the JMS API jar, but does not include a JMS client implementation.
If you want to run JMS tests, you will need to download the appropriate jars from the JMS provider.

Next, start JMeter and go through the Building a Test Plan section
of the User Guide to familiarize yourself with JMeter basics (for example, adding and removing elements).

Finally, go through the appropriate section on how to build a specific type of Test Plan.
For example, if you are interested in testing a Web application, then see the section
Building a Web Test Plan.
The other specific Test Plan sections are:

Once you are comfortable with building and running JMeter Test Plans, you can look into the
various configuration elements (timers, listeners, assertions, and others) which give you more control
over your Test Plans.

JMeter comes with Apache's Xerces XML parser. You have the option of telling JMeter
to use a different XML parser. To do so, include the classes for the third-party parser in JMeter's classpath,
and update the jmeter.properties file with the full classname of the parser
implementation.

To test a web server using SSL encryption (HTTPS), JMeter requires that an
implementation of SSL be provided, as is the case with Sun Java 1.4 and above.
If your version of Java does not include SSL support, then it is possible to add an external implementation.
Include the necessary encryption packages in JMeter's classpath.
Also, update system.properties to register the SSL Provider.

JMeter HTTP defaults to protocol level TLS. This can be changed by editing the JMeter property
https.default.protocol in jmeter.properties or user.properties.

The JMeter HTTP samplers are configured to accept all certificates,
whether trusted or not, regardless of validity periods, etc.
This is to allow the maximum flexibility in testing servers.

JMeter now includes the JMS API from Apache Geronimo, so you just need to add the appropriate JMS Client implementation
jar(s) from the JMS provider. Please refer to their documentation for details.
There may also be some information on the JMeter Wiki.

To install a release build, simply unzip the zip/tar file into the directory
where you want JMeter to be installed. Provided that you have a JRE/JDK correctly installed
and the JAVA_HOME environment variable set, there is nothing more for you to do.

There can be problems (especially with client-server mode) if the directory path contains any spaces.

The installation directory structure should look something like this (where X.Y is version number):

To run JMeter, run the jmeter.bat (for Windows) or jmeter (for Unix) file.
These files are found in the bin directory.
After a short time, the JMeter GUI should appear.

GUI mode should only be used for creating the test script, NON GUI mode must be used for load testing

There are some additional scripts in the bin directory that you may find useful.
Windows script files (the .CMD files require Win2K or later):

jmeter.bat

run JMeter (in GUI mode by default)

jmeterw.cmd

run JMeter without the windows shell console (in GUI mode by default)

jmeter-n.cmd

drop a JMX file on this to run a non-GUI test

jmeter-n-r.cmd

drop a JMX file on this to run a non-GUI test remotely

jmeter-t.cmd

drop a JMX file on this to load it in GUI mode

jmeter-server.bat

start JMeter in server mode

mirror-server.cmd

runs the JMeter Mirror Server in non-GUI mode

shutdown.cmd

Run the Shutdown client to stop a non-GUI instance gracefully

stoptest.cmd

Run the Shutdown client to stop a non-GUI instance abruptly

The special name LAST can be used with jmeter-n.cmd, jmeter-t.cmd and jmeter-n-r.cmd
and means the last test plan that was run interactively.

There are a few environment variables, that can be used to customize the JVM settings for JMeter. An easy way to set those is by creating a file named setenv.bat in the bin directory. Such a file could look like:

rem This is the content of bin\setenv.bat,
rem it will be called by bin\jmeter.bat
set JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=value"

The JVM_ARGS can be used to override JVM settings in the jmeter.bat script and will get set when starting JMeter, e.g.:

It may be necessary to set a few environment variables to configure the JVM used by JMeter. Those variables can be either set directly in the shell starting the jmeter script. For example setting the variable JVM_ARGS will override most pre-defined settings, for example

JVM_ARGS="-Xms1024m -Xmx1024m" jmeter -t test.jmx [etc.]

will override the HEAP settings in the script.

To set those variables permanently, you can place them in a file called setenv.sh in the bin directory. This file will be sourced when running JMeter by calling the jmeter script. An example for bin/setenv.sh could look like:

# This is the file bin/setenv.sh,
# it will be sourced in by bin/jmeter
# Use a bigger heap, but a smaller metaspace, than the default
export HEAP="-Xms1G -Xmx1G -XMaxMetaspaceSize=192m"
# Try to guess the locale from the OS. The space as value is on purpose!
export JMETER_LANGUAGE=" "

Java runtime options used when JMeter is started. Special options for operating systems might be added by JMeter.

JRE_HOME

Must point at your Java Runtime installation. Defaults to JAVA_HOME if empty. If JRE_HOME and JAVA_HOME are both empty, JMeter will try to guess JAVA_HOME. If JRE_HOME and JAVA_HOME are both set, JAVA_HOME is used.

JVM_ARGS

Java options to be used when starting JMeter. These will be added before JMETER_OPTS and after the other JVM options. Default is empty

JMeter automatically finds classes from jars in the following directories:

JMETER_HOME/lib

used for utility jars

JMETER_HOME/lib/ext

used for JMeter components and plugins

If you have developed new JMeter components,
then you should jar them and copy the jar into JMeter's lib/ext directory.
JMeter will automatically find JMeter components in any jars found here.
Do not use lib/ext for utility jars or dependency jars used by the plugins;
it is only intended for JMeter components and plugins.

If you don't want to put JMeter plugin jars in the lib/ext directory,
then define the property search_paths in jmeter.properties.

Utility and dependency jars (libraries etc) can be placed in the lib directory.

If you don't want to put such jars in the lib directory,
then define the property user.classpath or plugin_dependency_paths
in jmeter.properties. See below for an explanation of the differences.

Other jars (such as JDBC, JMS implementations and any other support libraries needed by the JMeter code)
should be placed in the lib directory - not the lib/ext directory,
or added to user.classpath.

JMeter will only find .jar files, not .zip.

You can also install utility Jar files in $JAVA_HOME/jre/lib/ext, or you can set the
property user.classpath in jmeter.properties

Note that setting the CLASSPATH environment variable will have no effect.
This is because JMeter is started with "java -jar",
and the java command silently ignores the CLASSPATH variable, and the -classpath/-cp
options when -jar is used.

If you are testing from behind a firewall/proxy server, you may need to provide JMeter with
the firewall/proxy server hostname and port number. To do so, run the jmeter[.bat] file
from a command line with the following parameters:

JMeter also has its own in-built Proxy Server, the HTTP(S) Test Script Recorder.
This is only used for recording HTTP or HTTPS browser sessions.
This is not to be confused with the proxy settings described above, which are used when JMeter makes HTTP or HTTPS requests itself.

For distributed testing, run JMeter in server mode on the remote node(s), and then control the server(s) from the GUI.
You can also use non-GUI mode to run remote tests.
To start the server(s), run jmeter-server[.bat] on each server host.

The script also lets you specify the optional firewall/proxy server information:

-H

[proxy server hostname or ip address]

-P

[proxy server port]

Example:

jmeter-server -H my.proxy.server -P 8000

If you want the server to exit after a single test has been run, then define the JMeter property server.exitaftertest=true.

To run the test from the client in non-GUI mode, use the following command:

jmeter -n -t testplan.jmx -r [-Gprop=val] [-Gglobal.properties] [-X]

where:

-G

is used to define JMeter properties to be set in the servers

-X

means exit the servers at the end of the test

-Rserver1,server2

can be used instead of -r to provide a list of servers to start.
Overrides remote_hosts, but does not define the property.

If the property jmeterengine.remote.system.exit is set to true (default is false),
then JMeter will invoke System.exit(0) after stopping RMI at the end of a test.
Normally this is not necessary.

Since 3.2, JMeter logging is not configured through properties file(s) such as jmeter.properties any more,
but it is configured through a Apache Log4j 2 configuration file
(log4j2.xml in the directory from which JMeter was launched, by default) instead.
Also, every code including JMeter and plugins MUST use SLF4J library
to leave logs since 3.2.

Here is an example log4j2.xml file which defines two log appenders and loggers for each category.

So, if you want to change the log level for org.apache.http category to debug level for instance,
you can simply add (or uncomment) the following logger element in log4j2.xml file before launching JMeter.

Log level for specific categories or root logger can be overridden directly on the command line (instead of modifying log4j2.xml) as well.
To do so, use the following options:

-L[category]=[priority]

Overrides a logging setting, setting a particular category to the given priority level.
Since 3.2, it is recommended to use a full category name (e.g, org.apache.jmeter or com.example.foo),
but if the category name starts with either jmeter or jorphan, org.apache.
will be prepended internally to the category name input to construct a full category name (i.e, org.apache.jmeter or org.apache.jorphan) for backward compatibility.

Examples:

jmeter -Ljmeter.engine=DEBUG

jmeter -Lorg.apache.jmeter.engine=DEBUG

jmeter -Lcom.example.foo=DEBUG

jmeter -LDEBUG

Differences in Logging : Old vs New Practices:

As JMeter uses SLF4J as logging API and Apache Log4j 2 as a logging framework since 3.2, not every log level
used before 3.2 can match exactly with one of the new available log levels provided by SLF4J/Log4j2.
Therefore, please keep the following differences and new suggested practices in mind
if you need to migrate any existing logging configurations and logging code.

Note:
Since 'FATAL_ERROR' is not supported by SLF4J API,
it is treated as 'ERROR' instead for existing code not to break.

Note:
'TRACE' level, which is less specific than 'DEBUG', is supported additionally since 3.2.
Look up SLF4J or Apache Log4J 2 documentations for details.

JMeter does not generally use pop-up dialog boxes for errors, as these would interfere with
running tests. Nor does it report any error for a mis-spelt variable or function; instead the
reference is just used as is. See Functions and Variables for more information.

If JMeter detects an error during a test, a message will be written to the log file.
The log file name is defined in the log4j2.xml file (or using the -j option, see below).
It defaults to jmeter.log, and will be found in the directory from which JMeter was launched.

The menu Options → Log Viewer
displays the log file in a bottom pane on main JMeter window.

In the GUI mode, the number of error/fatal messages logged in the log file is displayed at top-right.

Error/fatal counter

The command-line option -j jmeterlogfile allow to process
after the initial properties file is read,
and before any further properties are processed.
It therefore allows the default of jmeter.log to be overridden.
The jmeter scripts that take a test plan name as a parameter (e.g. jmeter-n.cmd) have been updated
to define the log file using the test plan name,
e.g. for the test plan Test27.jmx the log file is set to Test27.log.

When running on Windows, the file may appear as just jmeter unless you have set Windows to show file extensions.
[Which you should do anyway, to make it easier to detect viruses and other nasties that pretend to be text files …]

As well as recording errors, the jmeter.log file records some information about the test run. For example:

Prior to version 2.5.1, JMeter invoked System.exit() when a non-GUI test completed.
This caused problems for applications that invoke JMeter directly, so JMeter no longer invokes System.exit()
for a normal test completion. [Some fatal errors may still invoke System.exit()]
JMeter will exit all the non-daemon threads it starts, but it is possible that some non-daemon threads
may still remain; these will prevent the JVM from exiting.
To detect this situation, JMeter starts a new daemon thread just before it exits.
This daemon thread waits a short while; if it returns from the wait, then clearly the
JVM has not been able to exit, and the thread prints a message to say why.

The property jmeter.exit.check.pause can be used to override the default pause of 2000ms (2secs).
If set to 0, then JMeter does not start the daemon thread.

If you wish to modify the properties with which JMeter runs you need to
either modify the user.properties in the /bin directory or create
your own copy of the jmeter.properties and specify it in the command line.

Note: You can define additional JMeter properties in the file defined by the
JMeter property user.properties which has the default value user.properties.
The file will be automatically loaded if it is found in the current directory
or if it is found in the JMeter bin directory.
Similarly, system.properties is used to update system properties.

Parameters

Attribute

Description

Required

ssl.provider

You can specify the class for your SSL
implementation if you don't want to use the built-in Java implementation.

No

xml.parser

You can specify an implementation as your XML
parser. The default value is: org.apache.xerces.parsers.SAXParser

No

remote_hosts

Comma-delimited list of remote JMeter hosts (or host:port if required).
If you are running JMeter in a distributed environment, list the machines where
you have JMeter remote servers running. This will allow you to control those
servers from this machine's GUI

No

not_in_menu

A list of components you do not want to see in
JMeter's menus. As JMeter has more and more components added, you may wish to
customize your JMeter to show only those components you are interested in.
You may list their classname or their class label (the string that appears
in JMeter's UI) here, and they will no longer appear in the menus.

No

search_paths

List of paths (separated by ;) that JMeter will search for JMeter plugin classes,
for example additional samplers. A path item can either be a jar file or a directory.
Any jar file in such a directory will be automatically included in search_paths,
jar files in sub directories are ignored.
The given value is in addition to any jars found in the lib/ext directory.

No

user.classpath

List of paths that JMeter will search for utility and plugin dependency classes.
Use your platform path separator to separate multiple paths.
A path item can either be a jar file or a directory.
Any jar file in such a directory will be automatically included in user.classpath,
jar files in sub directories are ignored.
The given value is in addition to any jars found in the lib directory.
All entries will be added to the class path of the system class loader
and also to the path of the JMeter internal loader.

No

plugin_dependency_paths

List of paths (separated by ;) that JMeter will search for utility
and plugin dependency classes.
A path item can either be a jar file or a directory.
Any jar file in such a directory will be automatically included in plugin_dependency_paths,
jar files in sub directories are ignored.
The given value is in addition to any jars found in the lib directory
or given by the user.classpath property.
All entries will be added to the path of the JMeter internal loader only.
For plugin dependencies using plugin_dependency_paths should be preferred over
user.classpath.

No

user.properties

Name of file containing additional JMeter properties.
These are added after the initial property file, but before the -q and -J options are processed.

No

system.properties

Name of file containing additional system properties.
These are added before the -S and -D options are processed.

No

The command line options and properties files are processed in the following order:

-p propfile

jmeter.properties (or the file from the -p option) is then loaded

-j logfile

Logging is initialised

user.properties is loaded

system.properties is loaded

all other command-line options are processed

See also the comments in the jmeter.properties, user.properties and system.properties files for further information on other settings you can change.