/
get-started.xml
851 lines (800 loc) · 41.3 KB
/
get-started.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document[
<!ENTITY sect-num '1'>
<!ENTITY hellip "…" >
]>
<document next="build-test-plan.html" id="$Id$">
<properties>
<title>User's Manual: Getting Started</title>
</properties>
<body>
<section name="§-num;. Getting Started" anchor="get_started">
<section name="§-num;.0 Overview" anchor="overview">
When using JMeter you will usually follow this process:
<subsection name="§-num;.0.1 Test plan building" anchor="test_plan_building">
<p>To do that, you will <a href="get-started.html#running">run JMeter in GUI Mode.</a><br/>
Then you can either choose to record the application from a browser, or native application.
You can use for that the menu <menuchoice><guimenuitem>File</guimenuitem><guimenuitem>Templates...</guimenuitem><guimenuitem>Recording</guimenuitem></menuchoice><br/>
</p>
<p>
Note you can also manually build your plan. Ensure you read this <a href="test_plan.html">documentation</a> to understand major concepts.
</p>
You will also debug it using one of these options:
<ul>
<li><menuchoice><guimenuitem>Run</guimenuitem><guimenuitem>Start no pauses</guimenuitem></menuchoice></li>
<li><menuchoice><guimenuitem>Run</guimenuitem><guimenuitem>Start</guimenuitem></menuchoice></li>
<li><menuchoice><guimenuitem>Validate</guimenuitem></menuchoice> on <a href="component_reference.html#Thread_Group">Thread Group</a></li>
</ul>
<p>
and <a href="component_reference.html#View_Results_Tree">View Results Tree</a> renderers or Testers (CSS/JQUERY, JSON, Regexp, XPath).<br/>
Ensure you follow <a href="best-practices.html" >best-practices</a> when building your Test Plan.
</p>
</subsection>
<subsection name="§-num;.0.2 Load Test running" anchor="load_test_running">
<p>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:
<ul>
<li>Correct machine sizing in terms of CPU, memory and network</li>
<li>OS Tuning</li>
<li>Java setup: Ensure you install the latest version of Java supported by JMeter</li>
<li><b>Correct sizing of Java Heap</b>. By default JMeter runs with a heap of 512MB, this might not be enough for your test and depends on your test plan and number of threads you want to run</li>
</ul>
Once everything is ready, you will use Command-line mode (called <a href="#non_gui">Non-GUI mode</a>) to run it for the Load Test.
<note>Don't run load test using GUI mode !</note><br/>
Using Non-GUI mode, you can generate a CSV (or XML) file containing results and have JMeter <a href="generating-dashboard.html">generate an HTML report</a> at end of Load Test.
JMeter will by default provide a summary of load test while it's running. <br/>
You can also have <a href="realtime-results.html" >real-time results</a> during your test using <a href="component_reference.html#Backend_Listener">Backend Listener</a>.
</p>
</subsection>
<subsection name="§-num;.0.3 Load Test analysis" anchor="load_test_analysis">
Once your Load Test is finished, you can use the HTML report to analyze your load test. <br/>
</subsection>
</section>
<subsection name="§-num;.0.4 Let's start" anchor="lets_start">
<p>The easiest way to begin using JMeter is to first
<a href="http://jmeter.apache.org/download_jmeter.cgi">download the latest production release</a> 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.</p>
<p>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.</p>
<p>
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.
</p>
<note>
See the <a href="#classpath">JMeter Classpath</a> section for details on installing additional jars.
</note>
<p>Next, start JMeter and go through the <a href="build-test-plan.html">Building a Test Plan</a> section
of the User Guide to familiarize yourself with JMeter basics (for example, adding and removing elements).</p>
<p>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
<a href="build-web-test-plan.html">Building a Web Test Plan</a>.
The other specific Test Plan sections are:
<ul>
<li><a href="build-adv-web-test-plan.html">Advanced Web Test Plan</a></li>
<li><a href="build-db-test-plan.html">JDBC</a></li>
<li><a href="build-ftp-test-plan.html">FTP</a></li>
<li><a href="build-jms-point-to-point-test-plan.html">JMS Point-to-Point</a></li>
<li><a href="build-jms-topic-test-plan.html">JMS Topic</a></li>
<li><a href="build-ldap-test-plan.html">LDAP</a></li>
<li><a href="build-ldapext-test-plan.html">LDAP Extended</a></li>
<li><a href="build-ws-test-plan.html">WebServices (SOAP)</a></li>
</ul>
</p>
<p>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.</p>
</subsection>
</section>
<section name="§-num;.1 Requirements" anchor="requirements">
<p>JMeter requires that your computing environment meets some minimum requirements.</p>
<subsection name="§-num;.1.1 Java Version" anchor="java_versions">
<note>JMeter requires a fully compliant JVM 8, we advise that you install latest minor version of those major versions.
Java 9 is not tested completely as of JMeter 3.2.
</note>
<p>Because JMeter uses only standard Java APIs, please do not file bug reports if your JRE fails to run
JMeter because of JRE implementation issues.</p>
</subsection>
<subsection name="§-num;.1.2 Operating Systems" anchor="os">
<p>JMeter is a 100% Java application and should run correctly on any system
that has a compliant Java implementation.</p>
<p>Operating systems tested with JMeter can be viewed on
<a href="http://wiki.apache.org/jmeter/JMeterAndOperatingSystemsTested">this page</a>
on JMeter wiki.</p>
<p>Even if your OS is not listed on the wiki page, JMeter should run on it provided that the JVM is compliant.</p>
</subsection>
</section>
<section name="§-num;.2 Optional" anchor="optional">
<p>If you plan on doing JMeter development, then you will need one or more optional packages listed below.</p>
<subsection name="§-num;.2.1 Java Compiler" anchor="opt_compiler">
<p>If you want to build the JMeter source or develop JMeter plugins, then you will need a fully compliant JDK 8 or higher.</p>
</subsection>
<subsection name="§-num;.2.2 SAX XML Parser" anchor="opt_sax">
<p>JMeter comes with Apache's <a href="http://xml.apache.org/">Xerces XML parser</a>. 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 <a href="#classpath">classpath</a>,
and update the <a href="#configuring_jmeter">jmeter.properties</a> file with the full classname of the parser
implementation.</p>
</subsection>
<subsection name="§-num;.2.3 Email Support" anchor="opt_email">
<p>JMeter has extensive Email capabilities.
It can send email based on test results, and has a POP3(S)/IMAP(S) sampler.
It also has an SMTP(S) sampler.
</p>
</subsection>
<subsection name="§-num;.2.4 SSL Encryption" anchor="opt_ssl">
<p>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 <a href="#classpath">classpath</a>.
Also, update <a href="#configuring_jmeter"><code>system.properties</code></a> to register the SSL Provider.</p>
<p>
JMeter HTTP defaults to protocol level TLS. This can be changed by editing the JMeter property
<code>https.default.protocol</code> in <code>jmeter.properties</code> or <code>user.properties</code>.
</p>
<p><b>The JMeter HTTP samplers are configured to accept all certificates,
whether trusted or not, regardless of validity periods, etc.</b>
This is to allow the maximum flexibility in testing servers.</p>
<p>If the server requires a client certificate, this can be provided.</p>
<p>There is also the <complink name="SSL Manager"/>, for greater control of certificates.</p>
<note>The JMeter proxy server (see below) supports recording HTTPS (SSL)</note>
<p>
The SMTP sampler can optionally use a local trust store or trust all certificates.
</p>
</subsection>
<subsection name="§-num;.2.5 JDBC Driver" anchor="opt_jdbc">
<p>You will need to add your database vendor's JDBC driver to the <a href="#classpath">classpath</a> if you want to do JDBC testing.
Make sure the file is a jar file, not a zip.
</p>
</subsection>
<subsection name="§-num;.2.6 JMS client" anchor="opt_jms">
<p>
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 <a href="http://wiki.apache.org/jmeter/">JMeter Wiki</a>.
</p>
</subsection>
<subsection name="§-num;.2.7 Libraries for ActiveMQ JMS" anchor="libraries_activemq">
<p>
You will need to add the jar <code>activemq-all-X.X.X.jar</code> to your classpath, e.g. by storing it in the <code>lib/</code> directory.
</p>
<p>
See <a href="http://activemq.apache.org/initial-configuration.html">ActiveMQ initial configuration page</a>
for details.
</p>
</subsection>
<note>
See the <a href="#classpath">JMeter Classpath</a> section for more details on installing additional jars.
</note>
</section>
<section name="§-num;.3 Installation" anchor="install">
<p>We recommend that most users run the <a href="http://jmeter.apache.org/download_jmeter.cgi">latest release</a>.</p>
<p>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 <code>JAVA_HOME</code> environment variable set, there is nothing more for you to do.</p>
<note>
There can be problems (especially with client-server mode) if the directory path contains any spaces.
</note>
<p>
The installation directory structure should look something like this (where <code>X.Y</code> is version number):
<source>
apache-jmeter-X.Y
apache-jmeter-X.Y/bin
apache-jmeter-X.Y/docs
apache-jmeter-X.Y/extras
apache-jmeter-X.Y/lib/
apache-jmeter-X.Y/lib/ext
apache-jmeter-X.Y/lib/junit
apache-jmeter-X.Y/licenses
apache-jmeter-X.Y/printable_docs
</source>
You can rename the parent directory (i.e. <code>apache-jmeter-X.Y</code>) if you want, but do not change any of the sub-directory names.
</p>
</section>
<section name="§-num;.4 Running JMeter" anchor="running">
<br/>
<p>To run JMeter, run the <code>jmeter.bat</code> (for Windows) or <code>jmeter</code> (for Unix) file.
These files are found in the bin directory.
After a short time, the JMeter GUI should appear.
<note>GUI mode should only be used for creating the test script, NON GUI mode must be used for load testing</note>
</p>
<p>
There are some additional scripts in the bin directory that you may find useful.
Windows script files (the .CMD files require Win2K or later):
</p>
<dl>
<dt><code>jmeter.bat</code></dt><dd>run JMeter (in GUI mode by default)</dd>
<dt><code>jmeterw.cmd</code></dt><dd>run JMeter without the windows shell console (in GUI mode by default)</dd>
<dt><code>jmeter-n.cmd</code></dt><dd>drop a JMX file on this to run a non-GUI test</dd>
<dt><code>jmeter-n-r.cmd</code></dt><dd>drop a JMX file on this to run a non-GUI test remotely</dd>
<dt><code>jmeter-t.cmd</code></dt><dd>drop a JMX file on this to load it in GUI mode</dd>
<dt><code>jmeter-server.bat</code></dt><dd>start JMeter in server mode</dd>
<dt><code>mirror-server.cmd</code></dt><dd>runs the JMeter Mirror Server in non-GUI mode</dd>
<dt><code>shutdown.cmd</code></dt><dd>Run the Shutdown client to stop a non-GUI instance gracefully</dd>
<dt><code>stoptest.cmd</code></dt><dd>Run the Shutdown client to stop a non-GUI instance abruptly</dd>
</dl>
<note>The special name <code>LAST</code> can be used with <code>jmeter-n.cmd</code>, <code>jmeter-t.cmd</code> and <code>jmeter-n-r.cmd</code>
and means the last test plan that was run interactively.</note>
<p>
The environment variable <code>JVM_ARGS</code> can be used to override JVM settings in the <code>jmeter.bat</code> script.
For example:
</p>
<source>
set JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=propvalue"
jmeter -t test.jmx …
</source>
<p>
Un*x script files; should work on most Linux/Unix systems:
</p>
<dl>
<dt><code>jmeter</code></dt><dd>run JMeter (in GUI mode by default). Defines some JVM settings which may not work for all JVMs.</dd>
<dt><code>jmeter-server</code></dt><dd>start JMeter in server mode (calls jmeter script with appropriate parameters)</dd>
<dt><code>jmeter.sh</code></dt><dd>very basic JMeter script (You may need to adapt JVM options like memory settings).</dd>
<dt><code>mirror-server.sh</code></dt><dd>runs the JMeter Mirror Server in non-GUI mode</dd>
<dt><code>shutdown.sh</code></dt><dd>Run the Shutdown client to stop a non-GUI instance gracefully</dd>
<dt><code>stoptest.sh</code></dt><dd>Run the Shutdown client to stop a non-GUI instance abruptly</dd>
</dl>
<p>
It may be necessary to edit the jmeter shell script if some of the JVM options are not supported
by the JVM you are using.
The <code>JVM_ARGS</code> environment variable can be used to override or set additional JVM options, for example:
</p>
<source>
JVM_ARGS="-Xms1024m -Xmx1024m" jmeter -t test.jmx [etc.]
</source>
<p>
will override the HEAP settings in the script.
</p>
<subsection name="§-num;.4.1 JMeter's Classpath" anchor="classpath">
<p>JMeter automatically finds classes from jars in the following directories:</p>
<dl>
<dt><code>JMETER_HOME/lib</code></dt><dd>used for utility jars</dd>
<dt><code>JMETER_HOME/lib/ext</code></dt><dd>used for JMeter components and plugins</dd>
</dl>
<p>If you have developed new JMeter components,
then you should jar them and copy the jar into JMeter's <code>lib/ext</code> directory.
JMeter will automatically find JMeter components in any jars found here.
Do not use <code>lib/ext</code> for utility jars or dependency jars used by the plugins;
it is only intended for JMeter components and plugins.
</p>
<p>If you don't want to put JMeter plugin jars in the <code>lib/ext</code> directory,
then define the property <code>search_paths</code> in <code>jmeter.properties</code>.
</p>
<p>Utility and dependency jars (libraries etc) can be placed in the <code>lib</code> directory.</p>
<p>If you don't want to put such jars in the <code>lib</code> directory,
then define the property <code>user.classpath</code> or <code>plugin_dependency_paths</code>
in <code>jmeter.properties</code>. See below for an explanation of the differences.
</p>
<p>
Other jars (such as JDBC, JMS implementations and any other support libraries needed by the JMeter code)
should be placed in the <code>lib</code> directory - not the <code>lib/ext</code> directory,
or added to <code>user.classpath</code>.</p>
<note>JMeter will only find <code>.jar</code> files, not <code>.zip</code>.</note>
<p>You can also install utility Jar files in <code>$JAVA_HOME/jre/lib/ext</code>, or you can set the
property <code>user.classpath</code> in <code>jmeter.properties</code></p>
<p>Note that setting the <code>CLASSPATH</code> environment variable will have no effect.
This is because JMeter is started with "<code>java -jar</code>",
and the java command silently ignores the <code>CLASSPATH</code> variable, and the <code>-classpath</code>/<code>-cp</code>
options when <code>-jar</code> is used.</p>
<note>This occurs with all Java programs, not just JMeter.</note>
</subsection>
<subsection name="§-num;.4.2 Create Test Plan from Template" anchor="template">
<p>You have the ability to create a new Test Plan from existing template.</p>
<p>To do so you use the menu
<menuchoice>
<guimenuitem>File</guimenuitem>
<guimenuitem>Templates…</guimenuitem>
</menuchoice> or Templates icon:
<figure image="Select-Templates-Icon.png">Templates icon item</figure>
</p>
<p>A popup appears, you can then choose a template among the list:
<figure image="template_wizard.png">Templates popup</figure>
</p>
<p>A documentation for each template explains what to do once test plan is created from template.</p>
</subsection>
<subsection name="§-num;.4.3 Using JMeter behind a proxy" anchor="proxy_server">
<p>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 <code>jmeter[.bat]</code> file
from a command line with the following parameters:</p>
<dl>
<dt><code>-H</code></dt><dd>[proxy server hostname or ip address]</dd>
<dt><code>-P</code></dt><dd>[proxy server port]</dd>
<dt><code>-N</code></dt><dd>[nonproxy hosts] (e.g. <code>*.apache.org|localhost</code>)</dd>
<dt><code>-u</code></dt><dd>[username for proxy authentication - if required]</dd>
<dt><code>-a</code></dt><dd>[password for proxy authentication - if required]</dd>
</dl>
<b>Example</b>:
<source>jmeter -H my.proxy.server -P 8000 -u username -a password -N localhost</source>
<p>You can also use <code>--proxyHost</code>, <code>--proxyPort</code>, <code>--username</code>, and <code>--password</code> as parameter names</p>
<note>
Parameters provided on a command-line may be visible to other users on the system.
</note>
<p>
If the proxy host and port are provided, then JMeter sets the following System properties:
</p>
<ul>
<li><code>http.proxyHost</code></li>
<li><code>http.proxyPort</code></li>
<li><code>https.proxyHost</code></li>
<li><code>https.proxyPort</code></li>
</ul>
If a nonproxy host list is provided, then JMeter sets the following System properties:
<ul>
<li><code>http.nonProxyHosts</code></li>
<li><code>https.nonProxyHosts</code></li>
</ul>
<p>
So if you don't wish to set both http and https proxies,
you can define the relevant properties in <code>system.properties</code> instead of using the command-line parameters.
</p>
<p>
Proxy Settings can also be defined in a Test Plan, using either the <complink name="HTTP Request Defaults"/>
configuration or the <complink name="HTTP Request"/> sampler elements.
</p>
<note>JMeter also has its own in-built Proxy Server, the <complink name="HTTP(S) Test Script Recorder">HTTP(S) Test Script Recorder</complink>.
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.</note>
</subsection>
<subsection name="§-num;.4.4 Non-GUI Mode (Command Line mode)" anchor="non_gui">
<p>For load testing, you must run JMeter in this mode (Without the GUI) to get the optimal results from it. To do so, use
the following command options:</p>
<dl>
<dt><code>-n</code></dt><dd>This specifies JMeter is to run in non-gui mode</dd>
<dt><code>-t</code></dt><dd>[name of JMX file that contains the Test Plan].</dd>
<dt><code>-l</code></dt><dd>[name of JTL file to log sample results to].</dd>
<dt><code>-j</code></dt><dd>[name of JMeter run log file].</dd>
<dt><code>-r</code></dt><dd>Run the test in the servers specified by the JMeter property "<code>remote_hosts</code>"</dd>
<dt><code>-R</code></dt><dd>[list of remote servers] Run the test in the specified remote servers</dd>
<dt><code>-g</code></dt><dd>[path to CSV file] generate report dashboard only</dd>
<dt><code>-e</code></dt><dd>generate report dashboard after load test</dd>
<dt><code>-o</code></dt><dd>output folder where to generate the report dashboard after load test. Folder must not exist or be empty</dd>
</dl>
<p>The script also lets you specify the optional firewall/proxy server information:</p>
<dl>
<dt><code>-H</code></dt><dd>[proxy server hostname or ip address]</dd>
<dt><code>-P</code></dt><dd>[proxy server port]</dd>
</dl>
<b>Example</b>
<source>jmeter -n -t my_test.jmx -l log.jtl -H my.proxy.server -P 8000</source>
<p>
If the property <code>jmeterengine.stopfail.system.exit</code> is set to <code>true</code> (default is <code>false</code>),
then JMeter will invoke <code>System.exit(1)</code> if it cannot stop all threads.
Normally this is not necessary.
</p>
</subsection>
<subsection name="§-num;.4.5 Server Mode" anchor="server">
<p>For <a href="remote-test.html">distributed testing</a>, 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 <code>jmeter-server[.bat]</code> on each server host.</p>
<p>The script also lets you specify the optional firewall/proxy server information:</p>
<dl>
<dt><code>-H</code></dt><dd>[proxy server hostname or ip address]</dd>
<dt><code>-P</code></dt><dd>[proxy server port]</dd>
</dl>
<b>Example</b>:
<source>jmeter-server -H my.proxy.server -P 8000</source>
<p>If you want the server to exit after a single test has been run, then define the JMeter property <code>server.exitaftertest=true</code>.
</p>
<p>To run the test from the client in non-GUI mode, use the following command:</p>
<source>
jmeter -n -t testplan.jmx -r [-Gprop=val] [-Gglobal.properties] [-X]
</source>
where:
<dl>
<dt><code>-G</code></dt><dd>is used to define JMeter properties to be set in the servers</dd>
<dt><code>-X</code></dt><dd>means exit the servers at the end of the test</dd>
<dt><code>-Rserver1,server2</code></dt><dd>can be used instead of <code>-r</code> to provide a list of servers to start.
Overrides <code>remote_hosts</code>, but does not define the property.</dd>
</dl>
<p>
If the property <code>jmeterengine.remote.system.exit</code> is set to <code>true</code> (default is <code>false</code>),
then JMeter will invoke <code>System.exit(0)</code> after stopping RMI at the end of a test.
Normally this is not necessary.
</p>
</subsection>
<subsection name="§-num;.4.6 Overriding Properties Via The Command Line" anchor="override">
<p>Java system properties and JMeter properties can be overridden directly on the command lin
(instead of modifying <code>jmeter.properties</code>).
To do so, use the following options:</p>
<dl>
<dt><code>-D[prop_name]=[value]</code></dt><dd>defines a java system property value.</dd>
<dt><code>-J[prop_name]=[value]</code></dt><dd>defines a local JMeter property.</dd>
<dt><code>-G[prop_name]=[value]</code></dt><dd>defines a JMeter property to be sent to all remote servers.</dd>
<dt><code>-G[propertyfile]</code></dt><dd>defines a file containing JMeter properties to be sent to all remote servers.</dd>
<dt><code>-L[category]=[priority]</code></dt><dd>overrides a logging setting, setting a particular category to the given priority level.</dd>
</dl>
<p>The <code>-L</code> flag can also be used without the category name to set the root logging level.</p>
<p><b>Examples</b>:
</p>
<source>
jmeter -Duser.dir=/home/mstover/jmeter_stuff \
-Jremote_hosts=127.0.0.1 -Ljmeter.engine=DEBUG
</source>
<source>jmeter -LDEBUG</source>
<note>
The command line properties are processed early in startup, but after the logging system has been set up.
</note>
</subsection>
<subsection name="§-num;.4.7 Logging and error messages" anchor="logging">
<note>
Since 3.2, JMeter logging is not configured through properties file(s) such as <code>jmeter.properties</code> any more,
but it is configured through a <a href="http://logging.apache.org/log4j/2.x/" target="_blank">Apache Log4j 2</a> configuration file
(<code>log4j2.xml</code> in the directory from which JMeter was launched, by default) instead.
Also, every code including JMeter and plugins MUST use <a href="https://www.slf4j.org/" target="_blank">SLF4J</a> library
to leave logs since 3.2.
</note>
<p>
Here is an example <code>log4j2.xml</code> file which defines two log appenders and loggers for each category.
</p>
<source><![CDATA[<Configuration status="WARN" packages="org.apache.jmeter.gui.logging">
<Appenders>
<!-- The main log file appender to jmeter.log in the directory from which JMeter was launched, by default. -->
<File name="jmeter-log" fileName="${sys:jmeter.logfile:-jmeter.log}" append="false">
<PatternLayout>
<pattern>%d %p %c{1.}: %m%n</pattern>
</PatternLayout>
</File>
<!-- Log appender for GUI Log Viewer. See below. -->
<GuiLogEvent name="gui-log-event">
<PatternLayout>
<pattern>%d %p %c{1.}: %m%n</pattern>
</PatternLayout>
</GuiLogEvent>
</Appenders>
<Loggers>
<!-- Root logger -->
<Root level="info">
<AppenderRef ref="jmeter-log" />
<AppenderRef ref="gui-log-event" />
</Root>
<!-- SNIP -->
<!--
# Apache HttpClient logging examples
-->
<!-- # Enable header wire + context logging - Best for Debugging -->
<!--
<Logger name="org.apache.http" level="debug" />
<Logger name="org.apache.http.wire" level="error" />
-->
<!-- SNIP -->
</Loggers>
</Configuration>]]></source>
<p>
So, if you want to change the log level for <code>org.apache.http</code> category to debug level for instance,
you can simply add (or uncomment) the following logger element in <code>log4j2.xml</code> file before launching JMeter.
</p>
<source><![CDATA[ <Loggers>
<!-- SNIP -->
<Logger name="org.apache.http" level="debug" />
<!-- SNIP -->
</Loggers>]]></source>
<p>
For more detail on how to configure <code>log4j2.xml</code> file,
please see <a href="http://logging.apache.org/log4j/2.x/manual/configuration.html" target="_blank">Apache Log4j 2 Configuration</a> page.
</p>
<p>
Log level for specific categories or root logger can be overridden directly on the command line (instead of modifying <code>log4j2.xml</code>) as well.
To do so, use the following options:
</p>
<dl>
<dt>
<code>-L[category]=[priority]</code>
</dt>
<dd>
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, <code>org.apache.jmeter</code> or <code>com.example.foo</code>),
but if the category name starts with either <code>jmeter</code> or <code>jorphan</code>, <code>org.apache.</code>
will be prepended internally to the category name input to construct a full category name (i.e, <code>org.apache.jmeter</code> or <code>org.apache.jorphan</code>) for backward compatibility.
</dd>
</dl>
<p>
<b>Examples</b>:
</p>
<source>jmeter -Ljmeter.engine=DEBUG</source>
<source>jmeter -Lorg.apache.jmeter.engine=DEBUG</source>
<source>jmeter -Lcom.example.foo=DEBUG</source>
<source>jmeter -LDEBUG</source>
<p>
<b>Differences in Logging : Old vs New Practices</b>:
</p>
<p>
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.
</p>
<table>
<thead>
<tr>
<th>Category</th>
<th>Old Practices Before 3.2</th>
<th>New Practices Since 3.2</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Logger Reference
</td>
<td>
Logger reference through <code>LoggingManager</code>:
<source>LoggingManager.getLoggerFor(String category);
LoggingManager.getLoggerForClass();</source>
</td>
<td>
Use SLF4J API with either category or explicit class:
<source>LoggerFactory.getLogger(String category);
LoggerFactory.getLogger(Foo.class);</source>
</td>
</tr>
<tr>
<td>
Log Levels in Configuration or Command Line Arguments
</td>
<td>
Old Log Levels:
<ul>
<li>DEBUG</li>
<li>INFO</li>
<li>WARN</li>
<li>ERROR</li>
<li>FATAL_ERROR</li>
<li>NONE</li>
</ul>
</td>
<td>
Mapping to New Levels through SLF4J/Log4j2:
<ul>
<li>DEBUG</li>
<li>INFO</li>
<li>WARN</li>
<li>ERROR</li>
<li>ERROR</li>
<li>NONE</li>
</ul>
<div>
<em><b>Note:</b></em>
Since 'FATAL_ERROR' is not supported by SLF4J API,
it is treated as 'ERROR' instead for existing code not to break.
</div>
<div>
<em><b>Note:</b></em>
'TRACE' level, which is less specific than 'DEBUG', is supported additionally since 3.2.
Look up SLF4J or Apache Log4J 2 documentations for details.
</div>
</td>
</tr>
</tbody>
</table>
<note>
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 <a href="functions.html">Functions and Variables for more information</a>.
</note>
<p>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 <code>log4j2.xml</code> file (or using the <span class="code">-j</span> option, see below).
It defaults to <code>jmeter.log</code>, and will be found in the directory from which JMeter was launched.
</p>
<p>
The menu <menuchoice><guimenuitem>Options</guimenuitem><guimenuitem>Log Viewer</guimenuitem></menuchoice>
displays the log file in a bottom pane on main JMeter window.
</p>
<p>
In the GUI mode, the number of error/fatal messages logged in the log file is displayed at top-right.
</p>
<figure image="log_errors_counter.png">Error/fatal counter</figure>
<p>
The command-line option <code>-j jmeterlogfile</code> allow to process
after the initial properties file is read,
and before any further properties are processed.
It therefore allows the default of <code>jmeter.log</code> to be overridden.
The jmeter scripts that take a test plan name as a parameter (e.g. <code>jmeter-n.cmd</code>) have been updated
to define the log file using the test plan name,
e.g. for the test plan <code>Test27.jmx</code> the log file is set to <code>Test27.log</code>.
</p>
<p>When running on Windows, the file may appear as just <b>jmeter</b> 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 …]
</p>
<p>As well as recording errors, the <code>jmeter.log</code> file records some information about the test run. For example:</p>
<source>
2017-03-01 12:19:20,314 INFO o.a.j.JMeter: Version 3.2.20170301
2017-03-01 12:19:45,314 INFO o.a.j.g.a.Load: Loading file: c:\mytestfiles\BSH.jmx
2017-03-01 12:19:52,328 INFO o.a.j.e.StandardJMeterEngine: Running the test!
2017-03-01 12:19:52,384 INFO o.a.j.e.StandardJMeterEngine: Starting 1 threads for group BSH. Ramp up = 1.
2017-03-01 12:19:52,485 INFO o.a.j.e.StandardJMeterEngine: Continue on error
2017-03-01 12:19:52,589 INFO o.a.j.t.JMeterThread: Thread BSH1-1 started
2017-03-01 12:19:52,590 INFO o.a.j.t.JMeterThread: Thread BSH1-1 is done
2017-03-01 12:19:52,691 INFO o.a.j.e.StandardJMeterEngine: Test has ended
</source>
<p>The log file can be helpful in determining the cause of an error,
as JMeter does not interrupt a test to display an error dialogue.</p>
</subsection>
<subsection name="§-num;.4.8 Full list of command-line options" anchor="options">
<p>Invoking JMeter as "<code>jmeter -?</code>" will print a list of all the command-line options.
These are shown below.</p>
<source>
--?
print command line options and exit
-h, --help
print usage information and exit
-v, --version
print the version information and exit
-p, --propfile <argument>
the jmeter property file to use
-q, --addprop <argument>
additional JMeter property file(s)
-t, --testfile <argument>
the jmeter test(.jmx) file to run
-l, --logfile <argument>
the file to log samples to
-i, --jmeterlogconf <argument>
jmeter logging configuration file (log4j2.xml)
-j, --jmeterlogfile <argument>
jmeter run log file (jmeter.log)
-n, --nongui
run JMeter in nongui mode
-s, --server
run the JMeter server
-H, --proxyHost <argument>
Set a proxy server for JMeter to use
-P, --proxyPort <argument>
Set proxy server port for JMeter to use
-N, --nonProxyHosts <argument>
Set nonproxy host list (e.g. *.apache.org|localhost)
-u, --username <argument>
Set username for proxy server that JMeter is to use
-a, --password <argument>
Set password for proxy server that JMeter is to use
-J, --jmeterproperty <argument>=<value>
Define additional JMeter properties
-G, --globalproperty <argument>=<value>
Define Global properties (sent to servers)
e.g. -Gport=123
or -Gglobal.properties
-D, --systemproperty <argument>=<value>
Define additional system properties
-S, --systemPropertyFile <argument>
additional system property file(s)
-f, --forceDeleteResultFile
force delete existing results files before start the test
-L, --loglevel <argument>=<value>
[category=]level e.g. jorphan=INFO, jmeter.util=DEBUG or com.example.foo=WARN
-r, --runremote
Start remote servers (as defined in remote_hosts)
-R, --remotestart <argument>
Start these remote servers (overrides remote_hosts)
-d, --homedir <argument>
the jmeter home directory to use
-X, --remoteexit
Exit the remote servers at end of test (non-GUI)
-g, --reportonly <argument>
generate report dashboard only, from a test results file
-e, --reportatendofloadtests
generate report dashboard after load test
-o, --reportoutputfolder <argument>
output folder for report dashboard
</source>
<p>
Note: the JMeter log file name is formatted as a SimpleDateFormat (applied to the current date)
if it contains paired single-quotes, .e.g. '<code>jmeter_'yyyyMMddHHmmss'.log</code>'
</p>
<p>
If the special name <code>LAST</code> is used for the <code>-t</code>, <code>-j</code> or <code>-l</code> flags,
then JMeter takes that to mean the last test plan
that was run in interactive mode.
</p>
</subsection>
<subsection name="§-num;.4.9 non-GUI shutdown" anchor="shutdown">
<p>
Prior to version 2.5.1, JMeter invoked <code>System.exit()</code> when a non-GUI test completed.
This caused problems for applications that invoke JMeter directly, so JMeter no longer invokes <code>System.exit()</code>
for a normal test completion. [Some fatal errors may still invoke <code>System.exit()</code>]
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.
</p>
<p>
The property <code>jmeter.exit.check.pause</code> can be used to override the default pause of 2000ms (2secs).
If set to <code>0</code>, then JMeter does not start the daemon thread.
</p>
</subsection>
</section>
<section name="§-num;.5 Configuring JMeter" anchor="configuring_jmeter">
<p>If you wish to modify the properties with which JMeter runs you need to
either modify the <code>user.properties</code> in the <code>/bin</code> directory or create
your own copy of the <code>jmeter.properties</code> and specify it in the command line.
</p>
<note>
Note: You can define additional JMeter properties in the file defined by the
JMeter property <code>user.properties</code> which has the default value <code>user.properties</code>.
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, <code>system.properties</code> is used to update system properties.
</note>
<properties>
<property name="ssl.provider">You can specify the class for your SSL
implementation if you don't want to use the built-in Java implementation.
</property>
<property name="xml.parser">You can specify an implementation as your XML
parser. The default value is: <code>org.apache.xerces.parsers.SAXParser</code></property>
<property name="remote_hosts">Comma-delimited list of remote JMeter hosts (or <code>host:port</code> 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</property>
<property name="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.</property>
<property name="search_paths">
List of paths (separated by <code>;</code>) 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 <code>search_paths</code>,
jar files in sub directories are ignored.
The given value is in addition to any jars found in the <code>lib/ext</code> directory.
</property>
<property name="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 <code>user.classpath</code>,
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.
</property>
<property name="plugin_dependency_paths">
List of paths (separated by <code>;</code>) 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 <code>plugin_dependency_paths</code>,
jar files in sub directories are ignored.
The given value is in addition to any jars found in the <code>lib</code> directory
or given by the <code>user.classpath</code> property.
All entries will be added to the path of the JMeter internal loader only.
For plugin dependencies using <code>plugin_dependency_paths</code> should be preferred over
<code>user.classpath</code>.
</property>
<property name="user.properties">
Name of file containing additional JMeter properties.
These are added after the initial property file, but before the <code>-q</code> and <code>-J</code> options are processed.
</property>
<property name="system.properties">
Name of file containing additional system properties.
These are added before the <code>-S</code> and <code>-D</code> options are processed.
</property>
</properties>
<p>
The command line options and properties files are processed in the following order:
<ol>
<li><code>-p propfile</code></li>
<li><code>jmeter.properties</code> (or the file from the <code>-p</code> option) is then loaded</li>
<li><code>-j logfile</code></li>
<li>Logging is initialised</li>
<li><code>user.properties</code> is loaded</li>
<li><code>system.properties</code> is loaded</li>
<li>all other command-line options are processed</li>
</ol>
</p>
<p><b>
See also the comments in the <code>jmeter.properties</code>, <code>user.properties</code> and <code>system.properties</code> files for further information on other settings you can change.
</b></p>
</section>
</body>
</document>