skip to content

Report Generation Flags

3 roadmaps5 questions

Asking for the HTML report: -e -o at the end of a run or -g -o from an old JTL, the empty-folder rule, and the report generator properties that shape it. Interviewers probe the regenerate trick.

on this pageshow

explore

questions

5

Which JMeter command-line flags produce the HTML dashboard at the end of a non-GUI run?

level: juniorimportance: must knowfreq 76%

answer

  1. Two flags added to the non-GUI command
  2. One asks for it, one names a folder
  3. Long names mention report at end
  4. It refuses without the results file

basics

~10 s

Two flags: -e asks JMeter to build the dashboard once the run ends, and -o names the folder it is written to. Both sit next to -l, which JMeter demands before it accepts -e.

solid answer

~50 s

A non-GUI run that ends in a dashboard looks like `jmeter -n -t nightly.jmx -l results.jtl -e -o dashboard`. `-e` (long form `--reportatendofloadtests`) takes no argument; it tells JMeter to run the report generator after every engine has stopped. `-o` (`--reportoutputfolder`) takes the destination folder, and it wins over the exporter's own `output_dir` property; with no `-o` at all the HTML pages land in `<JMETER_HOME>/bin/report-output` while `statistics.json` lands in `report-output` under the directory you ran the command from. `-e` is accepted only together with `-l`: without it JMeter prints `Option -e requires -l option` followed by the usage block and never starts the test, because the dashboard is built by reading back the file `-l` writes. Passing `-o` on its own is legal and silently produces nothing: JMeter validates the folder, runs the test and generates no report. A finished folder holds `index.html`, `content/`, `sbadmin2-1.0.7/` and `statistics.json`.

code

bash · 8 lines
bash
# generate the dashboard when the run finishes
jmeter -n -t nightly.jmx -l results/nightly.jtl -e -o results/dashboard

# legal, runs the whole test, and writes no report at all
jmeter -n -t nightly.jmx -l results/nightly.jtl -o results/dashboard

# rejected before the test starts: Option -e requires -l option
jmeter -n -t nightly.jmx -e -o results/dashboard

go deeper

for a junior

Memorise the working line: -n -t plan.jmx -l results.jtl -e -o folder. Be able to say which of those two extra flags asks for the report and which one names the folder.

for a middle

Explain why -e is refused without -l: the generator reads back the file the -l result collector writes. Know that -o alone silently produces nothing.

for a senior

Know that generation runs in the same JVM after the last engine stops, that it re-reads the whole JTL, and that a generation failure is only logged, never fatal.

for a principal

Decide where report settings and output paths live for a fleet of jobs, so that a dashboard's location and shape are a property of the job definition rather than of whichever machine ran it.

## The command line, flag by flag The canonical form shipped in JMeter's own manual is one line: ``` jmeter -n -t nightly.jmx -l results.jtl -e -o dashboard ``` | Flag | Long form | Argument | What it does | |---|---|---|---| | `-n` | `--nongui` | none | run without the GUI | | `-t` | `--testfile` | the `.jmx` | the plan to run | | `-l` | `--logfile` | the JTL | where samples are written | | `-e` | `--reportatendofloadtests` | none | build the dashboard when the run ends | | `-o` | `--reportoutputfolder` | a folder | where the dashboard is written | Only the last two belong to the report generator. The other three are the ordinary non-GUI run, and `-e` is bolted onto it. ## Why -l is not optional JMeter checks the pair before anything starts. If `-e` is present and `-l` is not, it raises an illegal-usage error, prints `Option -e requires -l option` with the whole usage block, and returns without running the plan. The reason is mechanical rather than stylistic: `-e` attaches a report generator to the very `ResultCollector` that `-l` creates, and the generator's input is that file. No `-l`, no file, nothing to read. The same wiring explains a second rule that surprises people: with `-e`, the file named by `-l` must not already exist with content in it. JMeter refuses at startup with `Results file:<path> is not empty` rather than appending a second run's samples to yesterday's numbers. ## Where the output folder comes from `-o` does not reach the exporters directly. JMeter resolves the path, checks that it is safe to write to, and sets the internal property `jmeter.reportgenerator.outputdir` to its absolute path. Both shipped exporters — `HtmlTemplateExporter` for the HTML pages and `JsonExporter` for `statistics.json` — read their own `output_dir` property first and then let that global value override it. Two consequences: - `-o` beats `jmeter.reportgenerator.exporter.html.property.output_dir`, whatever the property file says; - with no `-o` anywhere the two exporters part company: the HTML pages fall back to the compiled default and land in `report-output` under JMeter's `bin` directory, while `statistics.json` follows the relative `output_dir=report-output` the shipped `reportgenerator.properties` sets for the JSON exporter and lands in `report-output` under whatever directory you ran the command from. Passing `-o` overrides both and puts them back together, which is another reason not to rely on the default on a build agent. ## The trap: -o without -e `-o` is not a request for a report. It is only a destination. A command such as `jmeter -n -t nightly.jmx -l results.jtl -o dashboard` is completely valid: JMeter validates the folder, runs the whole test, writes the JTL, and produces no dashboard at all. Nothing warns you. This is the single most common way a pipeline ends up with an empty artefact directory, and the fix is one character. ## When the report is actually built Generation happens after the test, in the same JVM, from a listener that fires when the last engine has stopped. The log shows `Generating Dashboard` and then `Dashboard generated`. Two operational details follow: 1. The work is done by re-reading the JTL from disk, so a very large results file costs real time and I/O at the end of the run. 2. If generation throws, the exception is caught, printed as `Error generating the report: ...` and logged — the JMeter process does not stop or change what it already did. A missing dashboard is therefore easy to overlook if nobody reads stderr. ## What the folder contains A generated dashboard is a static site: `index.html`, a `content/` directory holding the JSON data files and the pages, a bundled `sbadmin2-1.0.7/` theme, and `statistics.json` written by the JSON exporter. It is copied from the templates in `bin/report-template`, which you can point elsewhere with `jmeter.reportgenerator.exporter.html.property.template_dir`. Nothing in it needs a web server; opening `index.html` from disk is enough.

  • What does JMeter do if you pass -o but forget -e?
    It accepts the command, validates that the folder can be written to, runs the whole test and writes the JTL, then exits without generating anything. `-o` only names a destination; `-e` is the request. There is no warning, so the failure shows up as an empty artefact folder later.
  • Where does the dashboard go if you omit -o?
    Into two places, and that is the surprise. The HTML pages take the HTML exporter's compiled default and land in `report-output` under JMeter's `bin` directory, while `statistics.json` follows the relative `output_dir=report-output` that the shipped properties file sets for the JSON exporter and lands in `report-output` under your working directory. When `-o` is given, JMeter sets `jmeter.reportgenerator.outputdir` to the absolute path and that value overrides both, so the flag always wins over the property file.

saying these in an interview costs you the question

  • Thinks every non-GUI run writes a dashboard automatically
  • Passes -o alone and expects a report
  • Believes -e can work without a results file
  • Confuses -e with -g, which reads an existing file
  • Assumes the report is written beside the JTL
open as a page

How do you build a JMeter HTML dashboard from last night's results file without re-running the test?

level: middleimportance: must knowfreq 66%

basics

~10 s

Run the report generator on its own with -g: jmeter -g last-night.jtl -o dashboard. The flag takes an existing results file, so no plan is loaded and no load is generated.

open as a page

A JMeter run aborts with "Cannot write to ... as folder is not empty". What happened?

level: middleimportance: should knowfreq 58%

basics

~20 s

The folder given to -o already contains files. JMeter checks the report destination before the run starts and refuses rather than mix a new dashboard into an old one. The -f flag clears it first.

open as a page

A 4-minute JMeter run's dashboard shows only four points per over-time graph. What do you change?

level: seniorimportance: should knowfreq 44%

basics

~10 s

Lower jmeter.reportgenerator.overall_granularity. It defaults to 60000 milliseconds, so every over-time graph gets one point per minute. Set it in user.properties, keep it above 1000, and regenerate the existing results file.

open as a page

In a JMeter dashboard, how do you show only a few named transactions in the graphs?

level: seniorimportance: nice to knowfreq 34%

basics

~10 s

Set jmeter.reportgenerator.exporter.html.series_filter to a regular expression matching the series you want, ending it with (-success|-failure)?$ so the per-second graphs still match. An empty value, the default, filters nothing.

open as a page