HTML Dashboard Report

The generator only reads CSV. If jmeter.save.saveservice.output_format is set to xml, report generation fails at once with the 5.6.3 message Report generation requires csv output format, check 'jmeter.save.saveservice.output_format' property. CSV is the default, so this only bites plans or user.properties files that switched to XML to keep response data, which should not be done in load tests anyway.

The manual lists the save-service settings the generator relies on. They are all defaults in 5.6.3, so the requirement is really "do not turn them off". The table shows each one, its default and the parts of the report that need it.

Source: Generating Report Dashboard: Save Service configuration (User Manual) and Properties Reference: Results file configuration

Two related properties are worth knowing:

The dashboard handles transaction samples specially: some views include them, some ignore them and some let you choose. The manual gives two rules for the most accurate results:

The Bookshelf plan follows the first rule: every Transaction Controller is written with TransactionController.parent set to false, and with TransactionController.includeTimers set explicitly, as Logic Controllers & Transactions recommends.

Source: Generating Report Dashboard: Transaction Controller configuration (User Manual)

In a distributed run the controller writes one results file for all engines. Since 5.0 JMeter prefixes thread names with the engine host and port, so Active Threads Over Time counts the threads of every engine correctly without extra configuration. The manual still warns about one limitation: Time Vs Threads uses the number of threads for one server on its horizontal axis. Distributed testing itself is covered later in this section.

Run the Bookshelf load profile (50 threads, 60 s ramp-up, 660 s scheduler duration, so a 10-minute hold) and generate the dashboard in the same command. -e asks for the report at the end of the run, -o names the output folder, and -l is mandatory with -e (without it JMeter refuses to start with Option -e requires -l option).

The numbers are illustrative; they are the same run that is analysed in the walk-through below. Nothing about the report appears on the console: the generator logs Generating Dashboard and Dashboard generated to load.log, and only a failure is printed (Error generating the report: ...). Check the log, or simply the folder:

Open report-load/index.html in a browser. The report is static: it can be zipped, archived as a CI artifact or served from any web server.

Two safety checks protect earlier results, and both are a frequent cause of "the report was not generated":

A better habit for anything that must be compared later is a fresh, dated folder per run, for example -l results/2026-10-14-load.jtl -o results/2026-10-14-load-report, rather than -f.

Source: Generating Report Dashboard: Generation after load test (User Manual) and Getting Started: Command-Line Options (User Manual)

-g (--reportonly) generates a report from a results file and does nothing else; no test plan is needed. Because the CLI run above kept load.jtl, the same data can be reported again, for example with stricter APDEX thresholds and a 10-second granularity:

The file must be readable (Cannot read test results file : ... otherwise) and, again, the output folder must be empty or absent. A run that crashed or was killed usually leaves a valid JTL up to the last flushed line, so -g is also the way to get a report from an interrupted test.

The properties can just as well come from a file with -q, which keeps report settings under version control next to the plan:

Source: Generating Report Dashboard: Generation from an existing sample CSV log file (User Manual)

Since 5.1.1 the GUI has a dialog for the same operation (Tools → Generate HTML report). Its fields are:

Click Generate report and wait for the information dialog (Report created ! on success). The GUI does not generate the report in its own JVM: in 5.6.3 it starts a separate java -jar ApacheJMeter.jar process with the options -q (the chosen user.properties), -g (the results file), -j (a log file) and -o (the folder), and waits for it. The wait is bounded by generate_report_ui.generation_timeout, in milliseconds. The user manual tells you to raise it if generation takes more than two minutes; the properties reference and the 5.6.3 source give its default as 300000 (five minutes). For a large file, set it in user.properties before starting the GUI:

The same menu has a companion item, Tools → Export transactions for report (added to the Help menu in 3.3 and moved to the Tools menu introduced in 5.1), which builds a ready-made series_filter value from the Transaction Controller and sampler names in the open plan. It is described in the filtering section below.

Source: Generating Report Dashboard: Generation using GUI Tools menu (User Manual) and Properties Reference: Reporting configuration

All report settings are JMeter properties whose names start with jmeter.reportgenerator.. Their defaults live in bin/reportgenerator.properties, which, like jmeter.properties, should not be edited: its own header says to copy a property to user.properties and change it there, so upgrades do not wipe the change. The 5.6.3 generator first loads bin/reportgenerator.properties and then merges every JMeter property over it, so the effective precedence is:

A property can reference another one with the ${...} syntax. The shipped file does exactly that: every over-time chart sets its granularity to ${jmeter.reportgenerator.overall_granularity}, which is why changing one property changes all of them.

Source: Generating Report Dashboard: Configuring Dashboard Generation (User Manual)

Every general setting, with its default in 5.6.3:

The Statistics table and the percentile charts use three percentiles set by properties without the jmeter.reportgenerator. prefix: aggregate_rpt_pct1 (default 90), aggregate_rpt_pct2 (95) and aggregate_rpt_pct3 (99). Relative paths in report properties are resolved from the JMeter working directory, which is bin by default.

Source: Generating Report Dashboard: General settings (User Manual), Properties Reference: Reporting configuration and the 5.6.3 bin/reportgenerator.properties

APDEX turns a set of response times into a score between 0 and 1. Each successful sample is satisfied if its elapsed time is at or below the satisfied threshold, tolerating if it is at or below the tolerated threshold, and frustrated otherwise; the score is (satisfied + tolerating / 2) / total. Performance Testing Fundamentals explains the index itself. Two details of the JMeter implementation, read from the 5.6.3 source, matter when reading the table:

The global thresholds apply to every label unless apdex_per_transaction overrides them. Its format, from the manual, is sample_name:satisfied|tolerated, with entries separated by ;, values in milliseconds, and the name being either a literal label or a regular expression. Lines are continued with a trailing backslash.

The Bookshelf requirements give the search a tighter target than the rest (the same 800 ms limit that the Duration Assertion checks through the search_sla_ms run property), and judge whole journeys more leniently than single requests:

The names are regular expressions and must match the whole label (the 5.6.3 code uses matches(), not find()), so:

The thresholds in force are printed in the APDEX table itself, one row per label, which is the quickest way to check that an override matched. The shipped reportgenerator.properties shows an example that separates its first two entries with a comma; the manual, the change log and the unit test in the source all use semicolons, and the parser splits on ; only, so use semicolons.

Worked example. Over the run, GET /api/books (search) produced 3,330 samples: 3,060 at or under 300 ms, 232 between 301 and 800 ms, and 38 frustrated (20 slower than 800 ms plus 18 failures). Its APDEX is (3,060 + 232 / 2) / 3,330 = 3,176 / 3,330 = 0.954. With the default 500/1500 thresholds the same samples would score about 0.98, which is why thresholds must come from requirements, not from the defaults.

Source: Generating Report Dashboard: General settings (User Manual) and Changes history (3.2, Bug 60112)

overall_granularity sets the width of one time bucket on every over-time chart. All samples whose timestamp falls in a bucket are aggregated into one point: an average for response times, latencies, connect times and active threads, a rate per second for hits, codes, transactions and bytes.

Worked numbers for the Bookshelf run (660 s):

For a soak test of several hours the default of 60 s is reasonable; for a 10-minute load test 10 s is better. Individual charts can override the global value with their own property.set_granularity, and the Response Time Distribution uses a different kind of granularity: the width of its histogram buckets, 100 ms by default.

Source: Generating Report Dashboard: General settings (User Manual)

The Statistics table shows three percentiles, by default the 90th, 95th and 99th. Change them with aggregate_rpt_pct1, aggregate_rpt_pct2 and aggregate_rpt_pct3; the same properties drive the Aggregate Report listener, the Response Time Percentiles Over Time chart and the column headings (90th pct and so on). Since 5.3 the values may have decimals, so a 99.9th percentile is possible:

The manual warns that the dashboard’s percentiles can differ from the Aggregate Report’s, because the dashboard uses a different estimator. The difference is visible when the distribution is wide and there are few samples. Since 5.5 the estimator is configurable: backend_metrics_percentile_estimator=R_3 (no prefix) makes the dashboard agree with the Aggregate Report; the default is LEGACY. Percentiles are computed over a sliding window of statistic_window samples (20,000 by default); a label with more samples than the window gets an approximation that improves with a larger window at the cost of memory. Percentiles versus averages explains why the percentiles, not the average, carry the verdict.

Source: Generating Report Dashboard: General settings (User Manual) and Properties Reference

The generator has two kinds of filter, applied at different points, with different effects.

The suffix rule exists because some charts (Transactions Per Second, Total Transactions Per Second, Response Time Vs Request) name their series <label>-success and <label>-failure. A filter that matches only the bare label would hide them. The manual’s example keeps the series of two transactions:

Two more exporter properties refine the display filter:

The manual’s tables of discarding rules reduce to this: a series that matches series_filter is still discarded if show_controllers_only is true, the chart supports controller discrimination and the series is not a controller; a series that does not match is still kept if filters_only_sample_series is true and the chart does not support controller discrimination. Two configurations produce empty charts: show_controllers_only=true on a chart configured to exclude controllers, and a series_filter that matches no series.

Source: Generating Report Dashboard: Filtering mechanisms (User Manual)

A Bookshelf report with every label has nine rows: five requests and four transactions. For a business audience the four journeys are enough; for a developer the requests matter. The generator offers four ways to show only the transactions, with different consequences:

For the Bookshelf plan the display filter is the most useful option, because it keeps the request rows in the totals and in the error tables:

Tools → Export transactions for report generates such a line from the open plan. It collects the names of every Transaction Controller and sampler (except Flow Control Action and Debug Sampler) whose name does not look like a renamed child, joins them with | and shows the result in a dialog titled Export Transactions Result, ready to paste into user.properties. The pattern that recognises renamed children is exported_transactions_pattern; by default it matches a name followed by - and digits, which is what Apply Naming Policy produces.

Source: Generating Report Dashboard: Filtering mechanisms (User Manual) and Transaction Controller (Component Reference)

A closed-model run includes a ramp-up and a ramp-down that are not representative of the load being tested. The dashboard can be restricted to a time window with start_date and end_date, parsed with date_format. The filter uses each sample’s start time and is applied before any calculation, so it changes every table and chart.

The Bookshelf run started at 10:00:00 local time with a 60 s ramp-up and ended at 10:11:00. To report only the 10-minute hold, minus the last few seconds when threads stop:

The dates are interpreted in the JVM’s default time zone unless the format includes one. When a report is generated on a CI runner in UTC from a file recorded in another zone, add the zone to both the format and the values:

The steady-state report has fewer samples (about 8,900 instead of 9,798) and a slightly higher throughput, because the ramp-up seconds with few threads are gone. Compare reports of different runs only when they cover equivalent windows.

Source: Generating Report Dashboard: General settings (User Manual) and Changes history (3.1, Bug 59956)

Each chart is declared by a group of properties with the prefix jmeter.reportgenerator.graph.<graph_id>.. The manual notes that, in this early design, every default graph must be declared in properties, otherwise its view is empty; the declarations ship in reportgenerator.properties. Every graph supports:

The exporter can also override the axes of a chart with jmeter.reportgenerator.exporter.html.graph_options.<graph_id>.minX, maxX, minY and maxY, which is useful to give reports of several runs the same scale.

The graphs declared in the 5.6.3 reportgenerator.properties (all classes in org.apache.jmeter.report.processor.graph.impl):

Two exporters are declared: html (org.apache.jmeter.report.dashboard.HtmlTemplateExporter, with template_dir default report-template and output_dir default report-output, overridden by -o) and json (org.apache.jmeter.report.dashboard.JsonExporter, which writes statistics.json).

To rename a chart, override its title; to drop a chart’s transaction series, set exclude_controllers:

Source: Generating Report Dashboard: Graph settings (User Manual), Default graphs (User Manual) and Properties Reference: Reporting configuration

Since 5.0 the dashboard can plot any numeric column of the results file over time, including JMeter variables saved with sample_variables. Each custom graph is declared with a graph id that starts with custom_ and the class org.apache.jmeter.report.processor.graph.impl.CustomGraphConsumer, and appears on the Customs Graphs page. Its specific properties are:

The values of each bucket are averaged. Empty values and the literal null are skipped; a value that is not a number makes the generation fail (5.6.3 source). Besides saved variables, a custom graph can plot the native numeric columns of the CSV file, such as Latency, Connect or IdleTime.

Bookshelf example: hits per search. The search response has the form {"items":[...],"total":17}. A JSON Extractor on the search sampler stores total in a variable, the variable is saved in the results file, and a custom graph plots it, which shows whether the search terms in search-terms.csv return comparable result sizes over the run.

Add Add → Post Processors → JSON Extractor under GET /api/books (search):

Then, in user.properties (the sample_variables line must be in place before the run):

Three details matter. First, the manual’s own example writes set_X_Axis without the property. segment; the other specific properties use property., which is the documented form for graph-specific settings, so it is used for all of them here. Second, the default value null makes failed extractions invisible on the chart instead of plotting a fake zero. Third, a JMeter variable keeps its value until it is overwritten, and sample_variables writes the current value with every sample of the thread, so the view-book and loan samples that follow a search carry the same searchTotal. The chart is therefore a weighted trend, good for spotting a change in data, not an exact per-search average; for exact numbers, compute them from the JTL file restricted to the search label.

Source: Generating Report Dashboard: Generating customs graphs over time (User Manual), JSON Extractor (Component Reference) and Properties Reference: sample_variables

Everything above, collected in the user.properties that lives next to bookshelf-load.jmx:

JMeter reads user.properties from the bin directory by default; to keep it with the plan, pass it with -q user.properties, or put the report settings in a separate file such as report-steady.properties and pass that one to -g runs only.

Source: Generating Report Dashboard: Sample configuration (User Manual)

The first panel states what the report is about: Source file (load.jtl), Start Time and End Time of the samples used, and, when set, Filter for computing (sample_filter) and Filter for display (series_filter).

What to check:

One row per label, plus Total, with four columns: Apdex, T (Toleration threshold), F (Frustration threshold) and Label. Despite their headings, T holds the satisfied threshold and F the tolerated threshold in force for that row (the headings follow the APDEX naming, where T is the target time and F the frustration limit).

How to read it for Bookshelf:

A pie chart with two slices, PASS and FAIL (named OK and KO before 5.4), as percentages of all request samples. Transaction samples are not counted, so a failing request is not counted twice through its transaction.

For the run: 9,758 passed and 40 failed out of 9,798 samples, so FAIL is 0.41 %. Two questions follow. Is 0.41 % within the error budget of the requirements? And are the 40 errors spread over the run, or concentrated in the incident? The pie cannot answer the second question; Codes Per Second and Response Times Over Time can.

The central table, with column groups Executions (Label, #Samples, FAIL, Error %), Response Times (ms) (Average, Min, Max, Median, 90th pct, 95th pct, 99th pct), Throughput (Transactions/s) and Network (KB/sec) (Received, Sent). It has one row per label, transaction rows included, and a Total row. The table can be sorted by any column by clicking its heading.

How to read it for Bookshelf:

Source: Generating Report Dashboard: Overview (User Manual) and the 5.6.3 StatisticsSummaryConsumer, ApdexSummaryConsumer and RequestsSummaryConsumer sources

One row per type of error, with Number of errors, % in errors and % in all samples. The type is built from the response code and message (409/Conflict) or, when the response code is a success code but an assertion failed, from the assertion failure message (with assertion_results_failure_message=true, otherwise the generic Assertion failed). Transaction samples are not counted.

How to read it for Bookshelf:

One row per sampler that had errors, plus a Total row, with Sample, #Samples, #Errors and five pairs of Error and #Errors, the five most frequent error types of that sampler. Transaction samples are excluded by default (exclude_tc_from_top5_errors_by_sampler=true), and since 3.2 the table ignores series_filter, so it always shows every failing sampler.

This is the table to start from when the error rate is too high: it answers where before what. For Bookshelf it splits the 40 errors cleanly into a loan problem (conflicts on one endpoint) and a search problem (server errors and slow responses on another).

Source: Generating Report Dashboard: Overview (User Manual) and the 5.6.3 ErrorsSummaryConsumer and Top5ErrorsBySamplerConsumer sources

Every chart on this page has elapsed time on the horizontal axis, one point per overall_granularity bucket, a series per label that can be ticked or unticked, and zooming by selecting a range. The manual states for each chart whether it includes transaction samples.

Response Times Over Time (includes transaction samples). The average response time of each label per bucket. For Bookshelf the search line runs flat at about 150 ms, rises to about 600 ms in the 10:07 buckets and comes back; the view-book and loan lines barely move. A rise on one label only points at what that endpoint uses and the others do not (here the search query and its connection pool), whereas a rise on every line at once points at a shared resource (CPU, garbage collection, the network) or at the load generator. Averages smooth spikes away, so confirm on the next chart.

Response Time Percentiles Over Time (successful responses). For the successful samples only: Min, Max, Median and the three configured percentiles per bucket (since 5.1 computed from the samples of each bucket). For Bookshelf the 99th percentile goes from about 900 ms to 1,900 ms in the incident while the median moves from 140 to 400 ms: the tail degrades much more than the middle, the typical signature of queueing for a saturated pool. Because failed samples are excluded, a period with many fast errors can make this chart look better; read it next to Codes Per Second.

Active Threads Over Time. The average number of active threads per bucket, one series per thread group (the series name is the thread name up to its last space, so Bookshelf users 1-23 counts towards Bookshelf users). For Bookshelf it climbs from 0 to 50 over the first six 10-second points, stays flat at 50 and drops in the last bucket. This chart is the proof that the load profile ran as designed: a plateau below 50 means threads ended early, and a slow climb means the ramp-up was longer than configured. With the default 60 s granularity the whole ramp-up is one point of about 25, which hides it.

Bytes Throughput Over Time (ignores transaction samples). Bytes received and sent per second. For Bookshelf about 31,000 bytes/s received and 7,900 bytes/s sent at full load, a trivial bandwidth; it dips during the incident because fewer requests complete. On a real network, a received-bytes line that hits a flat ceiling while response times rise is the sign of a saturated link between generator and server.

Latencies Over Time (includes transaction samples). The average latency per bucket: the time from just before the request was sent to just after the first byte of the response arrived. For the small JSON responses of Bookshelf the latency is almost equal to the response time, so the server’s processing time dominates. A large and growing gap between response time and latency would mean the time is spent transferring the body (big payloads, slow network), not computing it.

Connect Time Over Time (includes transaction samples). The average time to establish the TCP connection (and TLS handshake, when used). With keep-alive, most Bookshelf samples reuse a connection and report 0, so the average sits near 1 ms; it moves during the ramp-up when new threads open their first connections. A connect time that climbs under load means the server is slow to accept connections (accept queue, connection limits, a load balancer), a different problem from slow processing.

Source: Generating Report Dashboard: Default graphs (User Manual) and Glossary (User Manual) for latency and connect time

Hits Per Second (ignores transaction samples). Finished requests per second, the server-side load. For Bookshelf it ramps to about 15.6 per second, matches the Little’s Law estimate, and dips to about 13 in the incident buckets. That dip is the closed-model feedback loop: slower responses keep the same 50 threads busy longer, so they send fewer requests, which hides part of the problem. In an open model the arrival rate would stay at the target and the queue would grow instead; see closed versus open workload models. Since 5.0 embedded resources are counted as hits as well.

Codes Per Second (ignores transaction samples). One series per response code. For Bookshelf: 200 at about 12.5 per second (searches, book views, logins, loan views), 201 at about 2 per second (created loans), a thin 409 series spread over the whole run, and a short burst of 500 and of Non HTTP response code: java.net.SocketTimeoutException at 10:07. The timing settles the question the Requests Summary left open: the server errors belong to the incident, the conflicts do not.

Transactions Per Second (includes transaction samples). One series per label and outcome, named <label>-success and <label>-failure. This is the chart that shows business throughput: about 3.6 TX Search only-success, 1.8 TX Browse and borrow-success and 0.6 TX Login heavy-success per second at full load, in the 60/30/10 ratio. A -failure series that appears only in some buckets locates failures in time per label.

Total Transactions Per Second (since 5.0). The same data summed into two series, Transaction-success and Transaction-failure. A quick view of whether the failure rate tracks the load or an event.

Response Time Vs Request (excludes transaction samples). The horizontal axis is the overall number of requests per second in a given second, the vertical axis the median response time of the requests completed in that second, with one series for successes and one for failures (5.6.3 source; the manual describes it as median and average). It is the closest the dashboard gets to a scalability curve: a flat cloud means the response time does not depend on the load within the range tested; a cloud that bends upwards at the right is the knee where the server starts to queue. For a constant-load Bookshelf run the points concentrate around 15 to 16 requests per second with medians around 120 ms, and the incident adds a few points at 13 per second with high medians, so the chart says little. It becomes informative for the stress profile, where the load climbs step by step.

Latency Vs Request (excludes transaction samples). The same with latency instead of response time; read it the same way, and compare with the previous chart to separate processing from transfer.

Source: Generating Report Dashboard: Default graphs (User Manual)

These charts have no time axis: they describe the distribution of response times over the whole run (or the window set by start_date and end_date).

Response Time Percentiles (includes transaction samples). For each label, the response time (vertical) at each percentile from 0 to 100 (horizontal). A healthy curve is flat for most of its length and rises only at the far right. For Bookshelf the search curve is flat around 150 ms up to the 90th percentile and then lifts sharply, reaching 912 ms at the 99th: the "hockey stick" of a tail caused by a short incident, not of a uniformly slow endpoint (that would shift the whole curve upwards).

Response Time Overview (excludes transaction samples). A bar chart that puts every request into one of four buckets using the global APDEX thresholds: Requests having response time ⇐ 500ms, Requests having response time > 500ms and ⇐ 1500ms, Requests having response time > 1500ms and Requests in error. For Bookshelf about 97 % fall into the first bar, 2.4 % into the second, a handful into the third, and 40 into the errors bar. It is a one-glance summary for non-specialists, but note that it ignores apdex_per_transaction: the search is judged against 500 ms here, not 300 ms.

Time Vs Threads (includes transaction samples). The average response time (vertical) for each number of active threads (horizontal), plus one -aggregated point per label at the average thread count and average response time. During the 60 s ramp-up of the Bookshelf run each thread count from 1 to 49 occurs for about 1.2 s, with a handful of samples each, so the left part of the chart is noisy; almost all samples sit at 50 threads. With a stepped stress profile (Concurrency Thread Group) the same chart shows how response time grows with concurrency. In distributed runs the horizontal axis counts the threads of one server only.

Response Time Distribution (includes transaction samples). A histogram per label: how many samples fell into each 100 ms bucket (responseTimeDistribution.property.set_granularity). For Bookshelf the view-book distribution is a single narrow peak at 0 to 100 ms; the search distribution has a main peak at 100 to 200 ms and a second, smaller bump at 300 to 500 ms. Two peaks usually mean two populations: cache hits and misses, two query plans, or, as in this run, two periods (normal and incident). Narrow the window with start_date and end_date to tell which.

Source: Generating Report Dashboard: Default graphs (User Manual)

The Customs Graphs → Over Time page shows one chart per custom_* graph. For Bookshelf, Bookshelf: books found per search stays between 15 and 20 for the whole run: the search terms return comparable result sizes, so the response times of different minutes are comparable too. A sudden drop to 0 would have meant the API returned empty lists (for example after a failed data load), which makes searches faster and the report misleadingly good.

A dashboard has more views than any single question needs. A practical order for a load-test verdict:

The dashboard says what happened on the client side. Why it happened needs server metrics for the same minutes (connection pools, CPU, garbage collection), collected during the run as described in Real-time Monitoring with Backend Listener, and the method of Analyzing Results & Finding Bottlenecks. The dashboard also inherits the limits of the closed model: a stalled server stops threads from sending, so the slowest moments are under-sampled (see coordinated omission).

The json exporter writes the Statistics table to statistics.json in the report folder, one object per label plus Total, with the fields transaction, sampleCount, errorCount, errorPct, meanResTime, medianResTime, minResTime, maxResTime, pct1ResTime, pct2ResTime, pct3ResTime, throughput, receivedKBytesPerSec and sentKBytesPerSec. A pipeline can gate on it without parsing HTML:

pct1ResTime to pct3ResTime follow aggregate_rpt_pct1 to aggregate_rpt_pct3, so a pipeline that changes the percentiles must change its checks too. Wiring this into Maven and GitHub Actions is covered later in this section.

Source: Changes history (5.1, Bug 63059) and the 5.6.3 bin/reportgenerator.properties