We begin with the problem it solves, because the table only makes sense once the problem is clear.

The raw data problem

During a load test, JMeter records a sample for every request: when it started, how long it took, whether it worked, how many bytes moved. A ten-minute test with a few hundred users can easily produce hundreds of thousands of such records. No human can read them line by line, and looking at a handful of them tells you nothing about the whole.

The solution in one sentence

The Aggregate Report is a listener, an element that collects results, which groups all samples by their label, the name of the request, and calculates statistics for each group: how many there were, the average and median time, the slow tail, the error share and the rate at which they were completed.

Why it is so widely used

It answers the questions people ask first. Is it fast enough? Is anything failing? Which requests are the slowest? How much traffic did we actually push through? Because it shows these answers in a single compact table that updates as the test runs, it became the default window into a test for generations of testers.

A handful of terms appear throughout this guide, and learning them now makes everything easier.

JMeter offers many ways to look at results, and each answers a slightly different question.

flowchart LR
  S[Samplers produce samples] --> L{Listeners}
  L --> A[Aggregate Report table]
  L --> T[View Results Tree]
  L --> W[Simple Data Writer to JTL file]
  W --> H[HTML Dashboard Report]
  W --> A2[Aggregate Report reading file later]
        

The table looks like magic until you see the simple bookkeeping behind it.

Samples arrive one by one

Each time a sampler finishes, JMeter creates a result object and offers it to every listener in scope. The Aggregate Report receives it and looks at its label. If the label is new, a new row is created; otherwise the sample is added to the existing row. At the same time a running total row is updated with every sample regardless of label.

What each row remembers

To compute counts and averages, a row needs only running sums. To compute the median and the percentile lines, it needs more: it must keep the individual elapsed times so it can find the value at a given position when they are sorted. This is why the Aggregate Report uses more memory than a simple counter, and why very long tests can make it heavy.

The table refreshes on a timer

Redrawing a table after every sample would swamp the machine, so the screen refreshes at intervals, while the underlying statistics are always up to date. In the graphical interface this redraw also costs processor time, one of the reasons real load tests should not rely on watching listeners.

sequenceDiagram
  participant V as Virtual User
  participant S as Sampler
  participant L as Aggregate Report
  participant R as Row for the label
  participant T as TOTAL row
  V->>S: Run request
  S-->>L: Finished sample with label and time
  L->>R: Find or create row, add sample
  L->>T: Add sample to overall totals
  L-->>L: Refresh screen at intervals
        

Setting it up takes a minute, and knowing the controls saves confusion later.

Every column answers one specific question, and knowing the question prevents misuse.

The three families of statistics describe different parts of the same crowd of samples.

The average hides the tail

Imagine ninety-five requests taking one second and five taking thirty seconds. The average comes to a little over two and a half seconds, a figure that matches neither the happy majority nor the miserable minority. The average blends them into a number nobody actually experienced.

The median shows the typical case

The median ignores how extreme the slow ones are and only asks what the middle sample looked like. In the example above it is one second, which truly describes what most users saw. Comparing the median with the average is a quick test of skew: when the average is much larger than the median, a slow tail is dragging it up.

Percentiles describe the experience of the unlucky

The ninety-fifth percentile asks how slow the unluckiest five percent were. In the example it is thirty seconds, exposing exactly what the average hid. Service agreements are often written in percentiles, because customers remember the slow experiences, not the average ones.

The ninety, ninety-five and ninety-nine lines are defaults, not laws of nature.

Where the values come from

The three percentile columns are controlled by settings in JMeter’s main property file. By changing those settings you can ask for different percentile lines, such as the ninety-eighth or the ninety-ninth and a half, so that the table matches the percentiles named in your own performance agreement. The change takes effect when JMeter is restarted, so decide before the test, not during it.

Match the table to the contract

If your organisation promises that ninety-five percent of requests will complete within two seconds, make sure the ninety-fifth line is present and treat it as the headline figure. Reporting a different percentile because it is the default invites arguments about whether the promise was kept.

How many samples a percentile needs

A high percentile is only meaningful when there are enough samples to populate its tail. The ninety-ninth percentile of two hundred samples is decided by the two slowest requests; a single hiccup changes it dramatically. As a rough habit, treat high percentiles from rows with only a few hundred samples as indicative rather than definitive, and repeat the test to see whether they hold.

A fast system that returns errors is not fast, so this column deserves as much attention as any time.

What counts as an error

A sample is counted as failed when its success flag is false. For web requests, that usually means a response code outside the successful range, a connection problem, a timeout, or a failed assertion that you added. Other protocols define failure in their own ways, such as a database error or an unexpected reply on a socket.

Why errors can be hidden

Without assertions, a server that returns an error page with a normal-looking code is counted as a success. The error column then shows zero even though every user saw a broken page. The reverse also happens: a strict assertion that is slightly wrong marks healthy responses as failures. The error column is only as honest as the checks behind it.

Fast failures flatter the averages

When a server is overloaded it often answers errors very quickly, because refusing a request is cheaper than serving it. Those fast failures pull the average and the median down, so a system in serious trouble can look faster than a healthy one. Always read response times together with the error share.

flowchart TD
  A[System under rising load] --> B{Overloaded?}
  B -- No --> C[Responses succeed, times grow gently]
  B -- Yes --> D[Server rejects requests quickly]
  D --> E[Error percentage rises]
  D --> F[Average time may fall]
  F --> G[Misleadingly good timing numbers]
  E --> H[Read time and errors together]
        

Throughput is the most misunderstood column, because it depends on how you built the test as much as on the system.

What it measures

Throughput is the number of requests completed divided by the time over which they were completed, shown per second, per minute or per hour depending on size. It tells you how much work the system actually did during the test window.

It depends on the test design

In JMeter, virtual users wait for each response before sending the next request, and timers add pauses between actions. The rate at which requests are sent therefore depends on the number of users, the response times and the think times together. A slow system produces lower throughput simply because each user spends longer waiting.

A simple law connects them

For a steady test, the number of active users is roughly the throughput multiplied by the time each user spends per cycle, including response time and think time. If one hundred users each complete a cycle in five seconds, the system handles about twenty cycles per second. If response times double and think times stay fixed, throughput falls even though nothing is wrong with the load generator.

flowchart LR
  U[Number of users] --> T[Throughput]
  R[Response time] --> T
  K[Think time] --> T
  T --> S[Requests per second the system handled]
        

Two small columns carry large clues about the network and about the weight of each page.

What they show

The received column shows how many kilobytes per second came back from the server, and the sent column shows how many went out. Both include headers as well as bodies. They are calculated over the same time window as throughput, so they rise and fall with it.

What they reveal

A sudden drop in received data with a rising error share often means the server has started returning short error messages instead of full pages. A very high received rate may mean the load generator’s own network link is becoming the limit, so response times start to include delays that belong to the generator. A high sent rate with large uploads can show where file or form submissions dominate the traffic.

The last row looks like the verdict on the whole test, and that is exactly why it misleads.

What the TOTAL row is

The final row combines every sample from every label into one set of statistics. Its average is the mean of all requests together, and its percentiles are calculated across the whole mixed pool. It is convenient, and it is often quoted in summaries as if it described the system as a whole.

Why mixing hides the truth

Different requests have very different natures. A light request that checks status may take twenty milliseconds, while a report generation may take eight seconds. If the light request is called a hundred times more often, it dominates the pool, and the total average looks excellent even though the heavy request is painfully slow. The reverse also happens. The total row describes your particular mix of traffic, not a property of the application.

Percentiles of a mixture are fragile

The ninety-fifth percentile of a mixed pool can fall entirely within one kind of request. If most requests are quick, the slow ones might sit above the ninety-fifth line, invisible in that figure. A change in the traffic mix alone, with no change in the application, can move the total percentiles noticeably.

Rows are only as meaningful as the labels that create them, and some elements add extra samples you may not expect.

Stable, descriptive labels

Each distinct sampler name becomes a row. Use names that describe the business action, such as opening the home page or adding an item to a basket, not technical details or changing values. A label that includes an identifier unique to each request produces a row per request and makes the table useless.

Transaction controllers and their two modes

A transaction controller groups several requests into one timed business step. Depending on its setting, it either generates a single parent sample and hides the children from listeners, or it produces an additional sample on top of the children, which remain visible. In the second mode the table contains both the individual requests and the combined step, and the total row counts them all.

Why this distorts totals

When children and the parent both appear, the total sample count and throughput include the same work twice, once as separate requests and once as the combined step. Averages in the total row then mix very short and much longer samples. Be clear which mode you chose, and read the total row accordingly.

The table summarises the entire run, but the interesting behaviour lives in one part of it.

Three phases in every test

At the beginning, users start gradually during the ramp-up, and the system is lightly loaded, with empty caches and unprepared connections. In the middle comes the steady state, when all users are active and behaviour has settled. At the end the users finish and the load falls away. The Aggregate Report blends all three phases into one set of numbers.

Why blending misleads

Ramp-up samples were taken under light load, so they pull averages down and make the system look healthier than it is at full load. Warm-up samples may be unusually slow because nothing is cached yet, pulling the maximum and the high percentiles up. Ramp-down samples may be distorted by users stopping at different moments.

flowchart LR
  A[Ramp-up: light and growing load] --> B[Warm-up effects: cold caches, new connections]
  B --> C[Steady state: full load, stable behaviour]
  C --> D[Ramp-down: users finishing]
  C --> E[Best period for conclusions]
        

What you can do

A number from a handful of samples is a rumour; a number from many thousands is evidence.

Why counts matter

Every statistic in a row is an estimate drawn from that row’s samples. The more samples there are, the less a single odd value can move the result. A row with forty samples can swing wildly between runs, while a row with forty thousand barely moves.

Rare operations

Some actions happen far less often than others, such as a sign-in performed once per user or a rarely used report. Their rows have few samples, and their percentiles are correspondingly shaky. Do not draw firm conclusions from such rows without extending the test or isolating that action in its own scenario.

Results are only useful if you can keep them, share them and look at them again later.

Write results to a file

The listener has a filename box. Entering a path there makes the listener write every sample it receives to that file, in the format and with the fields you choose through its configuration button. This produces the results log that other tools, including the dashboard generator, can read.

Read results from a file

The same box can load a previously saved file into the table. This is how you analyse a command-line run in the graphical interface afterwards: open the listener in a fresh plan, point it at the file and browse the rows. For very large files this loads many samples into memory, so allow enough memory or use the dashboard generator instead.

Save the table itself

A separate button saves the displayed table, with an option to include a header line. The result is a small text file with one line per label, ready to open in a spreadsheet, paste into a report or compare with a previous run.

A listener that helps you watch can also hurt the very test you are watching.

The cost of watching

In the graphical interface the Aggregate Report keeps individual times in memory and redraws its table regularly. Under heavy load with many users and a long duration, both costs grow. Garbage collection pauses lengthen, the processor spends time painting the screen instead of driving users, and the response times you record may include delays caused by the tool itself.

The command-line alternative

In non-GUI mode there is no screen to refresh, so the display cost disappears, but the listener’s memory cost remains if it stays in the plan. For large runs, the better design is a lightweight writer that saves samples to a file, with analysis done afterwards using the table or the dashboard generator.

The healthiest habit separates measuring from looking.

flowchart LR
  A[Build and debug plan in GUI] --> B[Remove heavy listeners]
  B --> C[Run in command-line mode with file writer]
  C --> D[Raw results file]
  D --> E[Aggregate Report loaded from file]
  D --> F[HTML dashboard report]
  E --> G[Compare rows with targets]
  F --> G
  G --> H[Archive raw file, table export and notes]
        

Several tools show similar numbers, and knowing the differences avoids choosing the wrong one.

Choosing among them

Use the Aggregate Report when you want a quick readable table with percentiles during development or when analysing a finished run. Use the Summary Report when you want a light listener and a measure of spread. Use the dashboard when the results must be shared, compared over time or presented with charts. Many teams use the table for fast checks and the dashboard for the official record.

Experienced engineers read the shape of the table, not just individual numbers.

A table informs; a decision needs agreed thresholds.

Agree targets before the test

Settle in advance which requests matter, which statistic judges each, and what limit means success. A typical rule reads: for each critical request, the ninety-fifth percentile must stay below a named time and the error share below a named percentage. Without prior agreement, every result becomes an argument.

Judge each request against its own target

A search might need to answer in one second, while a report may be allowed ten. Setting one limit for the whole table either blocks reasonable slow operations or lets important fast ones slip. Give each critical row its own limit.

Automate the verdict

For pipelines, a script can read the saved table or results file and compare the figures against the agreed limits, failing the stage when any is exceeded. Keep the limits in a version-controlled file so reviewers can see when and why they changed.

A subtle effect of how JMeter users behave can make a struggling system look better than it is.

Users wait for answers

A JMeter virtual user sends a request and waits for the response before doing anything else. If the system stalls for twenty seconds, that user produces no samples during the stall. A real crowd, arriving on its own schedule, would have kept arriving, and many more people would have experienced the stall.

What this does to the table

During a stall, fewer samples are recorded, and only the few that were already waiting show the long delay. The percentile lines are then calculated from a pool in which the slow period is under-represented. The table can understate how bad the stall was for the people who would have arrived during it.

Ways to reduce the effect

When several machines generate load, the table is built in a different place from where the samples are born.

Samples travel to the controller

In a distributed test, each worker runs its own threads and sends its samples back to the controller, where the listener summarises them. The sample counts in each row are the sum over all workers, and throughput describes the combined traffic. This is exactly what you want, but it comes with costs.

The controller can become the bottleneck

Receiving every sample from many workers takes processing and network capacity on the controller. A heavy listener on the controller, with its memory and screen updates, can slow the whole arrangement. For big distributed runs, let each worker write its own results file and merge the files afterwards, or use a lighter listener, and reserve rich analysis for after the test.

Clock and configuration differences

Samples carry time stamps from the machine that produced them. If worker clocks differ noticeably, time-based analysis such as throughput windows can be distorted. Keep worker clocks synchronised and confirm that every worker used identical settings, because a single misconfigured worker can quietly change a row’s numbers.

flowchart LR
  W1[Worker 1 samples] --> C[Controller]
  W2[Worker 2 samples] --> C
  W3[Worker 3 samples] --> C
  C --> A[Aggregate Report: combined rows]
  W1 -. optional .-> F1[Worker results file]
  W2 -. optional .-> F2[Worker results file]
  W3 -. optional .-> F3[Worker results file]
  F1 --> M[Merged file for later analysis]
  F2 --> M
  F3 --> M
        

The table shows symptoms as users saw them; the servers hold the causes.

Make the comparison easy

Record the start and end time of each test, and align the clocks of the generator and the servers, so a spike in the table can be matched to events elsewhere. Use the same time zone in all notes. A table without a time reference is hard to connect with anything else.

Results look harmless, but they can carry more than numbers.

These patterns appear again and again in teams that read their results well.

Besides the misleading total row, these mistakes look harmless and quietly spoil conclusions.

An honest look at benefits and costs shows when the table is the right tool.

A short order of operations avoids the stumbles described in this guide.

Stories show how the table helps, and how it can mislead, in everyday projects.

The Aggregate Report shows median and percentile columns. The Summary Report shows standard deviation and average response size but no percentiles, and it is lighter on memory.

It is the time that ninety percent of samples did not exceed. One in ten requests took longer than that value.

Yes. The three percentile values are set in JMeter’s property file, and a restart applies the change. Remember that older reports may have used different percentiles.

A slow tail is pulling the average up. Look at the high percentiles and the maximum to see how bad the slow samples are.

The number of completed requests divided by the elapsed time, shown per second, minute or hour. It is a result of your test design, not a setting.

To compute the median and percentiles it keeps individual elapsed times. Memory therefore grows with the number of samples, especially in long tests.

For large runs, no. Use a lightweight file writer and load the saved file into the table or the dashboard afterwards.

Open a plan containing an Aggregate Report, enter the path of the saved results file in its filename box and let it load. Allow enough memory for large files.

Depending on the transaction controller’s setting, it may add its own sample alongside the child samples, so both appear in the table and in the totals.

Only as background. It mixes different kinds of requests, so judge each critical request on its own row against its own target.

Without assertions, error pages with normal response codes count as successes. Add content checks so failures are detected.

There is no fixed number, but a few thousand per row gives much steadier values than a few hundred. Repeat runs to see how much the figure moves.

Yes. Use the save-table button, include the header option, and open the file in a spreadsheet for comparison and charts.

Use the table for fast checks and the dashboard for shareable reports with charts over time. Many teams use both on the same results file.

The Aggregate Report compresses a mountain of samples into one row per request, with counts, averages, medians, percentile lines, error shares, throughput and data rates. It is quick, readable and widely used, which is why it is so often misread. The average hides the slow tail, the TOTAL row blends unlike requests, error percentages depend on the assertions behind them, throughput reflects your test design, and the whole table blends ramp-up with steady state. Used with care, it is an excellent first look at a run. Read several columns together, judge each critical request against its own target, run heavy tests headless and analyse afterwards, and confirm the story with time-based charts and server metrics.