Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Analysis and Reporting

The HTML Dashboard Report and Custom Reports

Generate the JMeter HTML dashboard from a JTL file with -g or -e -o, read its charts, filter by labels and time, tune report properties and export raw data.

The HTML Dashboard Report is JMeter's built-in report generator. From a .jtl file it produces a folder of static HTML, CSS and JSON that you can open in a browser, attach to a build, or publish on an intranet. It shows percentiles, error tables, Apdex, throughput and many time-series charts. JMeter cannot run on this site, so this lesson describes the exact commands, files and properties; the runnable stand-in shows how the dashboard's time-series tables are built.

Prerequisites: save the right data

The report reads a CSV .jtl with a header row and these columns at least: timeStamp, elapsed, label, responseCode, responseMessage, threadName, success, bytes, sentBytes, grpThreads, allThreads, Latency, IdleTime, Connect. Default properties already save them (since JMeter 3.0). Put these in user.properties if your installation does not:

PROPERTIES
jmeter.save.saveservice.output_format=csv
jmeter.save.saveservice.timestamp_format=ms
jmeter.save.saveservice.print_field_names=true
jmeter.save.saveservice.thread_counts=true
jmeter.save.saveservice.latency=true
jmeter.save.saveservice.connect_time=true

Use milliseconds for timestamps: formatted dates need an extra property and break easily.

Generating the report

There are two common ways:

Terminal
# 1. During the test run (non-GUI)
jmeter -n -t plan.jmx -l results.jtl -e -o /reports/run-001

# 2. After the fact, from an existing results file
jmeter -g results.jtl -o /reports/run-002
  • -e generates the report at the end of the run; -g generates from a file.
  • -o names the output folder, which must be empty or not exist. JMeter refuses to overwrite an existing non-empty folder (create a new folder per run, for example named with a timestamp).
  • The result is index.html plus content, sbadmin2-1.0.7 (UI assets), and the data JSON files.

Run jmeter -g again with different filter properties to produce several reports from the same data.

Tour of the dashboard

  • Dashboard: APDEX table per transaction, request summary (pie of pass and fail), and a Statistics table with the same columns as the Aggregate Report, including the 90th, 95th and 99th percentiles, plus an Errors table that groups by message.
  • Charts > Over Time: response times over time, response time percentiles over time, active threads, bytes throughput, latencies, connect time.
  • Charts > Throughput: hits per second, codes per second, transactions per second, response time vs request.
  • Charts > Response Times: percentiles, percentile distribution, histogram, vs requests, and Response Time vs Threads.
  • Customs Graphs are available through plugins and custom configuration.

The three to look at first: Response Times Over Time (when did it degrade?), Active Threads Over Time (what was the load then?) and Transactions per Second (did throughput saturate?). Together they tell you the breaking point.

Filtering the data

Add properties to user.properties (or pass with -J when generating the report):

PROPERTIES
# Include only these labels (regex), exclude others
jmeter.reportgenerator.exporter.html.series_filter=^(GET /products|POST /checkout)(-success|-failure)?$
jmeter.reportgenerator.exporter.html.filters_only_sample_series=true

# Ignore the first 5 minutes (ramp-up) and the last minute
jmeter.reportgenerator.start_date=2026-05-01 10:05:00
jmeter.reportgenerator.end_date=2026-05-01 10:55:00
jmeter.reportgenerator.date_format=yyyy-MM-dd HH:mm:ss

# Time buckets for the over-time charts, in milliseconds
jmeter.reportgenerator.overall_granularity=60000

# Percentile columns
aggregate_rpt_pct1=90
aggregate_rpt_pct2=95
aggregate_rpt_pct3=99

The granularity matters: 1,000 ms gives a noisy chart for a long test; 60,000 ms smooths it. Choose a value that gives 100 to 300 points on the chart. Also exclude the ramp-up through the dates above, so statistics describe the steady state.

Sub-results and transaction controllers

If a Transaction Controller has Generate parent sample unticked, JMeter writes both the transaction sample and its children. The report can then show the transaction and each request. Tick the property jmeter.reportgenerator.exporter.html.filters_only_sample_series=true and use the series_filter to focus on transaction labels only so the page stays readable.

Time buckets by hand

The dashboard groups samples into buckets of the configured granularity and computes statistics for each bucket. This stand-in does the same on a tiny dataset: counts, average and 95th percentile per 10-second bucket.

Python Stand-in: build an over-time table like the dashboard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This is the shape you look for in the real dashboard: throughput rising with load, then response time and error rate climbing while throughput stops growing. The point where the lines bend is your capacity limit.

Beyond the built-in dashboard

  • Backend Listener (InfluxDB, Graphite, or Prometheus plugins) streams samples live to Grafana for real-time dashboards during long runs.
  • Raw CSV analysis with pandas, spreadsheets or SQL is great for custom questions: a per-user flow, comparison of two builds, SLO checks.
  • Reports in CI: archive the report folder as a build artifact (see non-GUI mode and CI).
  • Custom templates: copy bin/report-template and adjust the HTML or the reportgenerator.properties graph definitions, then pass jmeter.reportgenerator.template_dir.

Common mistakes

  1. Re-using the output folder: the run fails with "The output folder already exists and is not empty".
  2. An empty report because the .jtl has no header or uses a different timestamp format.
  3. Looking at one big average over a ramp-up of 30 minutes.
  4. Generating the report from the GUI listener's saved XML file: save CSV instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command generates a dashboard from an existing results file?

    -g reads a JTL file and -o names the output folder, which must be empty or not exist.
  2. 2. What is required of the -o folder?

    JMeter refuses to write into a non-empty folder to avoid mixing reports.
  3. 3. Which charts best show the breaking point of the system?

    Comparing load, throughput and response time shows where throughput saturates and times grow.
  4. 4. How do you exclude the ramp-up from the report?

    The start_date and end_date properties filter samples to a window, together with date_format.

Summary

  • The HTML dashboard is generated from a CSV JTL with -e -o or -g -o.
  • Keep timestamps in milliseconds and use a new empty output folder per run.
  • Read response time, threads and throughput together to find the limit.
  • Use report properties to filter labels, restrict the date range and set granularity.
  • Backend Listeners and raw CSV analysis complement the built-in report.

Next: Non-GUI Mode and Continuous Integration