Motivations for Creating Filter and Merge Plugins for Apache JMeter With Use Cases

Use Cases for Filters

Results Filter Plugin

The standard JMeter tool does not have a filter on the overall performance load test results.
Filters exist for some standard graphs and also when generating the HTML report, but it lacks a powerful global results filter tool.

It is often necessary to filter results to show only the pages and not all the URLs that make up the page. There are also "debug" or "JSR223 Groovy" samplers for intermediate calculations that are not pages and which are interesting to filter.

We can also make a global filter to remove the starting of threads (ramp-up) and the stopping of threads (ramp-down).

The filter allows you to remove from the results a warm-up period of the application at the beginning of the performance test, which often has quite high times during the first call and then significantly better times after the warm-up period.

The filter also allows for a ramp-up with several steps to filter the results step by step and therefore to have results over a time interval corresponding to the step.

The filter tool does not change the dates of the result file.

The filter tool also allows you to change the format of the output file by reading the input file in CSV or XML format and outputting a result file in CSV or XML format.

Merge Results Plugin

As standard with JMeter, it is quite difficult to compare the results of two or more test results. The Merge plugin greatly simplifies the comparison of multiple performance tests.

If we simply concatenate the results and there is not too much time difference between the end of the first and second performance tests, the graph results will be correct.

If the time gap between the two tests is significant, then the result will not be good visually for graphs with two blocks separated by a large space. The first performance test is at the beginning of the graph on the left, and the second performance test is at the end of the graph on the right.

The import of two result files for tests launched at quite distant times produced a graph result of KO.

The merge tool allows you to shift the start of the test to a fixed date so that the performance tests start on this fixed date and the graphs will be correct, but you have to display the times in relative duration and not in absolute date time.

The merge tool changes the dates of the result of the merged file to 01/01/2000.

Before the Merge

On the left are the response times of the P1_SEARCH page for the TEST1 shot and on the right are the response times of the P1_SEARCH page for the TEST2 shot.

After the Merge (Merging of the 2 Files)

On the same graph, in red are the response times of the P1_SEARCH page of TEST1 and in blue, the P1_SEARCH page of TEST2. The labels are prefixed to distinguish the origin of the results file.

You can also filter the same file 3 times with 3 different time filters by indicating the number of virtual users on a step as a prefix (_40, _80, 120).

• Note: The character "_" in front of 40 and 80 allows you to keep the alphabetical and numerical sort order; you can also use the character "0".

The output file (the result of merging the same file with time filters on the 3 trays) is reread in a summary report for example.

In this summary report, we find all the times on the 3 steps with the prefix of the label of the same load test.

Filter and Merge Plugins Manuals

Filter Plugin Manual

The Filter tool is installed with the plugin management tool: Plugins Manager
URL of the plugins manager documentation. The name displayed in the plugins manager tool is: "Filter Results Tool."

The plugin installation will download the plugin library in <JMETER_HOME>\lib\ext : - jmeter-plugins-filterresults-<version>.jar.

Additionally, two shell scripts will be in <JMETER_HOME>\bin:

• FilterResults.bat for Windows
• FilterResults.sh for Linux/Unix

The Filter tool is only in the Command Line Interface (documentation).

The parameters are as follows:

• Required parameters:
  • --input-file <filenameIn>: In reading, the results file of a performance test in CSV or XML (JTL) format
  • --output-file <filenameFilteredOut>: In writing, the filtered results file
• Optional parameters:
  • --success-filter <true/false>: true - Only success samplers; false - all results by default
  • --include-labels <labels list>: A list of labels to include with ',' separator or a regular expression
  • --exclude-labels <labels list>: A list of labels to exclude with ',' separator or a regular expression
  • --include-label-regex <true/false>: The label(s) to include a regular expression or strings (true - regex, false - not regex)
  • --exclude-label-regex <true/false>: The label(s) to exclude a regular expression or strings (true - regex, false - not regex)
  • --start-offset <sec>: Remove the start of the results before n seconds
  • --end-offset <sec>: Removes the end of the results after n seconds (the filter is the interval [start-offset, end-offset])
  • --save-as-xml <true/false>: false - CSV format by default; true - save XML format

An example command line to start filtering on a file is as follows:

<JMETER_HOME>/bin/FilterResults.sh --output-file filteredout.xml --input-file inputfile.csv --include-label-regex true --include-labels "P[1-3].*" --start-offset 2 --end-offset 180 --success-filter true --save-as-xml true

The tool is launched with the following:

• Linux shell script (FilterResults.sh) from the JMeter bin directory
• Input results file (--input-file inputfile.csv)
• Filtered results file (--output-file filteredout.xml)
• The filter of labels to include is a regex (--include-label-regex true).
• Filter of labels to include regex (--include-labels "P[1-3].*)
• Filter of the start of the results, remove the first 2 seconds (--start-offset 2)
• Filter of the end of the results, remove the results after 180 seconds from the start of the test (--end-offset 180)
• Keep only OK results (--success-filter true)
• The output format of the results file in XML (--save-as-xml true)

Note: For large result files, you need to add/modify the –Xmx (maximum heap memory) parameter in the Java program launch script.

The maximum memory size is about 3 times the input file size.

In bold, the modification of the Java launch parameter with a maximum heap memory size of 1GB (-Xmx):

• java -Xmx 1G -jar %~dp0\..\lib\cmdrunner-2.0.jar --tool FilterResults %*

Shell scripts are in <JMETER_HOME>\bin.

The filter can also be done with the Maven plugin jmeter-graph-tool-maven-plugin.

In this example, the pom.xml file uses the jmeter-graph-tool-maven-plugin plugin in version 1.2 and filters the result file twice.

• The 1st filter is done on a regular expression on the labels.
• The 2nd filter is done on a time interval with the offsets since the start of the test.

Note that it is possible with one result filter to use a filter on labels and an offset range filter at the same time.

    <groupId>io.github.vdaburon</groupId>
    <artifactId>jmeter-graph-tool-maven-plugin</artifactId>
    <version>1.2</version>
    <executions>
        <execution>
            <id>create-graphs</id>
            <goals>
            <goal>create-graph</goal>
            </goals>
            <phase>verify</phase>
            <configuration>
<directoryTestFiles>${project.build.directory}/jmeter/testFiles</directoryTestFiles>
                <filterResultsTool>
                    <filterResultsParam>
<inputFile>${project.build.directory}/jmeter/results/resultats.csv</inputFile>
<outputFile>${project.build.directory}/jmeter/results/res_label_filtred.csv</outputFile>
                        <successFilter>false</successFilter>
                        <includeLabels>0.*</includeLabels>
                        <includeLabelRegex>true</includeLabelRegex>
                    </filterResultsParam>
                    <filterResultsParam>
<inputFile>${project.build.directory}/jmeter/results/resultats.csv</inputFile>
<outputFile>${project.build.directory}/jmeter/results/res_time_filtred.jtl</outputFile>
                        <successFilter>false</successFilter>
                        <startOffset>2</startOffset>
                        <endOffset>20</endOffset>
                        <saveAsXml>true</saveAsXml>
                    </filterResultsParam>
                </filterResultsTool>
              ...

Merge Plugin Manual

Java Swing Interface in JMeter GUI

To install the Merge plugin, it is best to use the plugin manager (see earlier link).

The name displayed in the plugins manager tool is: "Merge Results."

The installation of the plugin will download the plugin library in <JMETER_HOME>\lib\ext: - jmeter-plugins-mergeresults-<version>.jar.

The merge tool has a Swing interface in JMeter GUI:

Selection of 2 to 4 result files to merge (Input File Name): You must indicate the path to the result files to merge as well as the "Prefix label", the offset and label filters are optional.

The result file of the merge is indicated at the bottom (Merge and write results output file: Filename).

Then you must click on the "Merge" button to merge the files.

Command Line Interface to Launch the Merge Tool

Another way to merge result files is to use the shell script in the <JMETER_HOME>/bin directory.

• JMeterPluginsCMD.bat for Windows shell
• JMeterPluginsCMD.sh for Linux/Unix shell

The shell script needs several parameters:

1. A properties file with information about the input files and filters
2. The name of the plugin "MergeResults"
3. The name of the file containing the merged information

Example of launching under Windows:

<JMETER_HOME>\bin\JMeterPluginsCMD.bat --plugin-type MergeResults --input-jtl merge-results.properties --generate-csv test1-test2_merge.csv

• The parameter --plugin-type is set to MergeResults.
• The parameter --input-jtl merge-results.properties specifies a properties file.
• The parameter --generate-csv test1-test2_merge.csv specifies the name of the result file of the file merge.
• The merge-results.properties file contains the information of the input files and filters.
• Up to 4 input files are possible in a merge.
• The <file number> is 1, 2, 3, or 4.

The mandatory parameters in the properties file are:

• inputJtl<file number>=<input file name>
• prefixLabel<file number>=<test prefix> (to distinguish the results)

The other parameters are optional:

• includeLabels<file number>= labels to include separated by commas “,” or a regular expression
• excludeLabels<file number>= labels to exclude separated by commas “,” or a regular expression
• includeLabelRegex<file number>=: Is this a regular expression for labels to include?
• excludeLabelRegex<file number>=: Is this a regular expression for labels to exclude?
• startOffset<file number>= removes the first n seconds since the start of the test.
• endOffset<file number>= removes the n seconds after the start of the test.

Example of merge-results.properties file with two files to merge:

# === FILE 1 ===
inputJtl1=test1.csv
prefixLabel1=TEST1:
includeLabels1=P[0-9].*
excludeLabelsl=
includeLabelRegex1=true
excludeLabelRegex1=
startOffset1=
endOffset1=1500

# === FILE 2 ===
inputJtl2=test2.csv
prefixLabel2=TEST2:
includeLabels2=P[0-9].*
excludeLabels2=
includeLabelRegex2=true
excludeLabelRegex2=
startOffset2=
endOffset2=1500

If the number of files to merge exceeds four, then the first four files must be merged into a merge1.csv result. Then merge the next two or more files into the merge2.csv result file.
Finally, merge the merge1.csv and merge2.csv files without prefixes and without time filter into a merge3_final.csv file.

• Note: Merging a single file allows filtering by label and time filter, but has the consequence of changing the date and time of the load test to the reference date (01/01/2000) =>. The graphs are then necessarily in relative time display and not in absolute time. In the case of a single file, it is better to use another filter tool (FilterResults) and not the merge tool so as not to modify the time of the shot samplers.

Additional Link

• Merge Results plug-in