The record that JMeter writes after every single request.

The simple definition

A sampler is a JMeter element that does one piece of work, such as sending an HTTP request, running a database query, or calling a message queue. Each time a sampler runs, JMeter measures what happened and stores the facts in a package. That package is the Sampler Result, often called a sample result or simply a sample. One run of one sampler by one thread produces one Sampler Result.

The package holds the name of the step, the time it took, the status code, the size of the data, the thread that ran it, whether it passed, and much more. It can also hold the full request and the full response if you choose to keep them. Because every report is made of these packages, a mistake in understanding them leads to a mistake in understanding the whole test.

Why it deserves your attention

Most people look at the summary table at the end of a test and never open a single result. This is risky. A summary can show an average of one second while the individual results show that one request in twenty took ten seconds, or that half of the “successful” requests actually returned an error page with a normal status code. The summary only tells the truth when the results underneath are correct and well understood.

Four neighbouring words that are often mixed up.

JMeter has many moving parts, and the vocabulary around results can be confusing. Clear definitions help you talk to your team and read the documentation without getting lost.

How they relate

The relationship is a simple chain. A sampler runs and creates a Sampler Result. Assertions look at the result and attach their verdicts. Listeners then receive the result and turn it into something a human can read or a file that a tool can process. Understanding this chain tells you where to look when something is wrong. If a number looks wrong, it may be a problem in what the sampler measured, in what an assertion decided, or in what a listener chose to save or display.

Knowing the order of events explains why some elements can see the result and others cannot.

JMeter follows a fixed order every time a sampler is about to run. Understanding this order tells you when a Sampler Result is born and who may touch it.

flowchart TD
    A["Configuration elements apply their settings"] --> B["Pre-processors run"]
    B --> C["Timers calculate and apply their delays"]
    C --> D["Sampler runs and measures the request"]
    D --> E["Sampler Result is created"]
    E --> F["Post-processors read the result and extract values"]
    F --> G["Assertions check the result"]
    G --> H["Listeners receive the finished result"]
        

The sequence in plain words

Why the order matters in practice

Because timers run before the sampler starts measuring, a five-second think time never appears in the response time of the request. Because assertions run after post-processors, an extractor can capture a value from a response even if an assertion later marks that same response as failed. Because listeners come last, they always see the final status after all assertions have spoken. These simple facts explain many puzzling situations that confuse beginners.

A map of the whole record before we study each part in detail.

A Sampler Result is a bundle of fields. Some describe time, some describe size, some describe status, and some describe the request and the response. Here is a map. Later chapters examine each group carefully.

Not every field is saved by default

The in-memory Sampler Result holds everything, but when results are written to a file, JMeter saves only a chosen set of fields. By default it saves a compact set that covers the essentials: timestamp, elapsed time, label, response code, response message, thread name, data type, success flag, failure message, bytes, sent bytes, group threads, all threads, URL, latency, idle time and connect time. Heavy fields such as response data, request headers and response headers are not saved unless you ask for them. This choice protects the file size and the memory of the load generator.

Four clocks, each telling a different part of the story.

Timing is the heart of performance testing, and the Sampler Result carries several time measurements. Many people use only one, the elapsed time, and miss valuable information in the others.

flowchart LR
    A["Request starts"] --> B["Connection opened: connect time"]
    B --> C["Request sent and server works"]
    C --> D["First byte arrives: latency ends"]
    D --> E["Rest of response downloads"]
    E --> F["Last byte arrives: elapsed time ends"]
        

Reading the clocks together

The clocks become powerful when read together. If the connect time is large, the problem is probably in the network path, in name resolution, or in the secure handshake. If connect time is small but latency is large, the server took a long time to start responding, which points to slow processing in the application or the database. If latency is small but the elapsed time is much larger, the server answered quickly but the response is large or the network is slow at carrying it. The gap between elapsed time and latency is roughly the download time.

What the server said, and what JMeter says when the server says nothing.

HTTP response codes

For web requests, the response code is the three-digit status the server returns, and the response message is the short text that goes with it, such as “OK” or “Not Found”. Codes in the two hundreds mean success. Codes in the three hundreds mean redirection. Codes in the four hundreds mean the client made a mistake. Codes in the five hundreds mean the server failed. The HTTP sampler treats the four-hundred and five-hundred families as failed samples by default, unless an assertion or setting says otherwise.

When the response code is not a number

Sometimes the request never reaches a normal server answer. The connection may be refused, the name may not be found, the secure handshake may fail, or the response may time out. In these cases, JMeter fills the response code with a text that starts with “Non HTTP response code” followed by the name of the technical error. The response message then starts with “Non HTTP response message” followed by details. These entries are very valuable, because they tell you that the problem happened before the application could answer.

A request can return a happy status code and still be a failure. The success flag exists to tell the truth.

The Sampler Result carries a success flag, a simple yes or no that says whether the sample passed. The sampler sets an initial value based on its own rules, such as the status code family. Then every assertion attached to the sample gets a chance to change it. If any assertion fails, the final success flag becomes false and a failure message is attached to explain why.

Why status codes alone are not enough

Many modern applications return a normal success code even when the business action failed. A log-in page may return a normal page with the words “wrong password”. A search may return a normal page with the words “no results because of an internal error”. A payment service may return a success code with an error message inside the data. If you only trust the status code, all of these appear green, and your report shows a perfect error rate while real users are suffering.

flowchart TD
    A["Sampler sets the first success value from its own rules"] --> B["Assertion 1 checks the result"]
    B --> C["Assertion 2 checks the result"]
    C --> D{"Did any assertion fail?"}
    D -->|"Yes"| E["Success flag becomes false and a failure message is stored"]
    D -->|"No"| F["Success flag stays as it was"]
        

Balancing strictness and cost

Assertions cost CPU time, because JMeter must search or parse each response. A very large number of heavy assertions can slow down the load generator and distort the timings. The art is to choose a few checks that prove the business action worked, such as one unique word on the confirmation page, rather than scanning the whole body for many patterns. A well-chosen assertion is cheap and powerful.

Ignore status and non-failing assertions

The Response Assertion has an option called ignore status, which tells it to ignore the failure already caused by the status code, so that a deliberate error response, such as a planned 404 in a negative test, can be counted as a pass. Use this carefully and only for tests where the error is the expected result.

How much data moved, and why that explains so many slow requests.

The Sampler Result records the amount of data in both directions. These numbers help you understand bandwidth use, spot unexpectedly large responses, and explain why one request is slower than another even though the server worked equally hard.

Using sizes to find problems

Sizes are a quick sanity check. A page that normally weighs two hundred kilobytes and suddenly weighs two kilobytes under load is almost certainly an error page, even if the status code looks normal. A response that is much larger than expected may indicate missing compression or a data query that returns too many rows. Total received bytes divided by the test time gives the network throughput, which tells you whether the network card or the link to the server could be the limit.

Who ran it, when it ran and how busy the test was at that moment.

Label

The label is the name of the sample. By default it is the name of the sampler in your test plan. The label is the main key used to group samples in every summary and graph, so a clear and stable naming scheme is one of the most useful habits in performance testing. Chapter 18 treats naming in detail.

Thread name

The thread name combines the name of the thread group and the number of the thread, such as “Shoppers 1-37”. It tells you which virtual user produced the sample. When one user keeps failing while others succeed, the thread name lets you look at that one user’s whole journey and find what was special about it, such as bad test data.

Timestamp

The timestamp records the moment of the sample as a number of milliseconds since the first of January 1970 in universal time. It is the basis of every graph that has time on the horizontal axis. Because all load generators should use synchronised clocks, timestamps from several machines can be placed on one common timeline.

Active threads

Two fields record how busy the test was at the moment of the sample. Group threads is the number of active threads in the same thread group. All threads is the number of active threads in the whole test, across all groups on that machine. These fields let you plot response time against the number of active users, which is exactly the graph you need to find the point where the system begins to struggle.

flowchart LR
    A["Samples with timestamp and active threads"] --> B["Group by time"]
    B --> C["Response time over time"]
    B --> D["Throughput over time"]
    B --> E["Active threads over time"]
    C --> F["Combined view: how speed changes as users grow"]
    D --> F
    E --> F
        

The part of the record that proves exactly what JMeter sent.

When a response looks wrong, the first question is always “what did we really send?”. The Sampler Result keeps the answer, as long as it was kept in memory or saved. The request-side fields are your evidence.

The most common discovery

The most frequent discovery when reading the request side is that a variable was not replaced. The test plan said to send a token, but the request shows the text of the variable name instead of its value. This means the extractor that should have captured the token did not find it in the previous response. Without the request-side evidence, the failure would look like a server problem. With it, the cause is clear within seconds.

What came back, and how JMeter understands it.

Response data

The response data is the body of the answer: a page, a data message, a file. JMeter keeps it in memory while extractors and assertions work on it. For text answers it can be searched with patterns. For binary answers, such as images or documents, JMeter keeps the bytes but does not try to read them as text. Response data is often the biggest piece of a Sampler Result, and it is the biggest reason that results consume memory.

Response headers

The response headers are the extra information the server sends with its answer: content type, content length, cache rules, cookies to set, and server identification. Extractors can read them to capture values, and assertions can check them. They are also very useful for diagnosing caching, compression and security settings.

Data type and encoding

The data type tells whether the response is treated as text or as binary. The encoding tells JMeter which character set to use when it turns bytes into text. If the encoding is wrong, accented letters and many non-English characters appear as strange symbols, and text checks may fail even though the server answered correctly. If an assertion on a non-English page fails mysteriously, check the encoding first.

Sometimes one Sampler Result contains smaller ones inside it.

A single Sampler Result can have sub-results, which are smaller results nested inside a parent result. This happens in three common situations, and each of them changes how you read your numbers.

flowchart TD
    P["Parent sample: Checkout page"] --> C1["Sub-result: main HTML"]
    P --> C2["Sub-result: style file"]
    P --> C3["Sub-result: script file"]
    P --> C4["Sub-result: product image"]
        

Why this matters for your numbers

If you group several steps in a transaction and also keep the individual steps in your summary, then the same time is counted twice, once inside the child and once inside the parent. A report that adds everything together would show inflated throughput and counts. Most reports solve this by showing only the parent, or by letting you choose whether to include the sub-samples. Know which one your report uses before you compare tests.

The transaction controller options

The transaction controller has an option to generate a parent sample. When it is on, the group appears as one result with the others hidden inside. When it is off, the group’s total appears as an extra sample next to the individual samples. Another option decides whether the pauses from timers and the work of pre-processors and post-processors inside the group are counted in the total. Choose deliberately: counting the pauses gives the full user-experienced time of a journey, while leaving them out gives the pure system time.

The debugging window where most people first meet the record.

The View Results Tree listener shows each sample as an entry on the left. Selecting an entry shows its details on the right, split into tabs. The tab named Sampler Result is the one that displays the summary of the record, and the other tabs show the request and the response in detail.

A reliable reading routine

The result is not only for reports. The test itself reads it to make decisions.

While a test runs, other elements read the Sampler Result of the sampler they belong to, and use it to drive the next steps. This is how a script copes with changing session tokens, dynamic identifiers and conditional journeys.

Extractors read fields from the result

Extractors are post-processors that search the result and store what they find in variables. A Regular Expression Extractor, a JSON Extractor, an XPath Extractor and a Boundary Extractor can all read the response body. Many of them can also be told to read other fields of the result: the response headers, the request headers, the address, the response code or the response message. This choice is called the field to check, and it is the way to capture a token from a header or the status code into a variable for later decisions.

Scope: main sample and sub-samples

When a result has sub-results, such as embedded resources, an extractor or assertion needs to know which part to read. The scope setting offers choices: the main sample only, the sub-samples only, both, or the value of a variable. The default is the main sample only. If a value you need appears in a sub-sample, such as a redirect step, but your extractor looks only at the main sample, the extractor will quietly find nothing.

Script elements and the previous result

Script-based elements in JMeter can reach the whole Sampler Result of the sampler that just ran, through an object commonly called the previous result. From there a script can read any field: the code, the timings, the sizes, the headers. It can also change the result, for example to mark a sample as failed for a business reason, or to change the label. This is powerful, but it should be used sparingly, because scripts cost CPU time and can slow the generator under high thread counts.

Choosing what to keep decides what you can learn afterwards.

During a real test, results should be written to a file as they are produced. This file is commonly called a JTL file. The command-line option for the results file is the standard way to produce it in non-GUI mode. After the test, tools and the report generator read this file to produce tables and graphs.

CSV or XML

JMeter can save results as comma-separated rows or as XML records. The CSV format is compact and fast, and it is the default in recent versions and the one most analysis tools expect. The XML format can hold full request and response data and nested sub-results with more structure, but it is much larger and slower to write. For load tests, CSV with a carefully chosen set of fields is usually the right choice. XML is useful for short debugging runs where you need every detail.

Choosing which fields to save

The set of saved fields is controlled by settings in the JMeter properties file or in the configuration window of a listener. The defaults cover the essentials. You can add fields you need and remove those you do not. Adding the response data or the headers makes files much larger, and the load generator must hold and write all that data. Saving only failed samples with full details, while saving a light record for every sample, is a common compromise.

Every number in a report is a calculation over many small records.

Listeners like the Summary Report, the Aggregate Report and the HTML dashboard take thousands of Sampler Results and group them, usually by label. For each group they calculate familiar statistics. Knowing exactly which field feeds which statistic lets you judge whether a number deserves your trust.

Percentiles tell the truth about slow users

The average hides the tail. If ninety-five requests take one second and five take twenty seconds, the average is nearly two seconds, but one in twenty users waited twenty seconds. The ninety-fifth and ninety-ninth percentile lines expose this. Always read the percentile lines before the average, and always report them next to it.

The garbage-in rule

Statistics cannot fix bad samples. If the success flag is wrong because nobody asserted on content, the error percentage is wrong. If the label is unstable, the groups are wrong. If the timestamp is not synchronised across machines, the timeline is wrong. If ramp-up samples are mixed with steady-state samples, the averages are wrong. Check the quality of the samples before you believe the summary.

flowchart LR
    A["Thousands of Sampler Results"] --> B["Group by label"]
    B --> C["Filter out ramp-up and ramp-down periods"]
    C --> D["Calculate average, percentiles, errors, throughput"]
    D --> E["Tables and graphs in the report"]
        

Every result has a price, and a heavy test pays it thousands of times per second.

It is easy to forget that each Sampler Result is a real object living in the memory of the load generator. With a few threads this is invisible. With hundreds of threads sending many requests per second, the total weight becomes significant, and the cost of keeping, processing and writing results can slow the test tool itself.

How to keep the cost low

A good name today saves hours of confusion when you read results next month.

The label is the key that groups samples. Every table and graph in your report is built on it. A careful naming scheme makes reports readable and comparable. A careless one produces thousands of useless groups and makes trends invisible.

Pattern 1: order and readability

Start labels with a number that shows the order of the step in the journey, followed by a short meaningful name, such as “01 Open home page”, “02 Search product” and “03 Add to cart”. Reports then sort in the natural order of the user journey, and anyone can read them without opening the test plan.

Pattern 2: stable labels, never dynamic ones

Never put changing values, such as user identifiers or order numbers, in a label. If the label contains a variable that changes on every request, each sample creates its own group. A test with a hundred thousand requests then shows a hundred thousand rows in the report, and the load generator and the report tool both choke. Put changing values in the request, not in the name.

Pattern 3: one name per business action

Give each business action one clear name, and keep that name identical across tests and across script versions. When names change, history is lost, and you cannot compare today’s result with last month’s.

Pattern 4: separate main steps from helper steps

Some samplers are only technical helpers, such as fetching a token or setting up data. Give them a clear prefix so you can exclude them from user-facing statistics. Otherwise, your average response time mixes real user steps with internal helpers, and the average no longer describes the user experience.

Pattern 5: group embedded resources sensibly

When pages download many images and scripts, those sub-results can flood the report with rows. Use the option that places resources under their parent, or use a naming pattern that groups them, so the report focuses on business steps.

Results travel, and the way they travel changes what you can see.

Results from many workers

In a distributed test, each worker machine runs the test plan and creates its own Sampler Results. These results are sent back to the controller, which collects them into one stream for the listeners and the results file. This means that the controller handles the results of every worker, and under high load it can become a bottleneck if the results are heavy or very numerous.

Sending modes

JMeter lets you choose how workers send results to the controller. The standard mode sends each sample as soon as it is ready, which gives the most live view but costs the most network and processing. Other modes send samples in batches, send summarised statistics instead of every sample, remove heavy data such as response bodies before sending, or store samples on disk and send them in the background. The right choice depends on your test size. A light mode such as batching or stripping heavy data is usually recommended for large tests, while the standard mode suits small ones.

flowchart TD
    W1["Worker 1: creates Sampler Results"] --> S["Result sending mode: standard, batch or lighter"]
    W2["Worker 2: creates Sampler Results"] --> S
    W3["Worker 3: creates Sampler Results"] --> S
    S --> C["Controller: collects all results"]
    C --> F["Results file and listeners"]
        

Live dashboards through a backend listener

The Backend Listener sends aggregated information from the Sampler Results to an external metrics database while the test is running. Typical numbers sent are the count of samples, the average and percentile response times, the error counts and the active thread counts, grouped by label and by time interval. A dashboard tool then draws live graphs. This lets you watch the test as it happens, correlate it with server metrics on the same screen, and stop the test early if something is clearly wrong.

A Sampler Result can contain the exact secrets your application protects.

Because a Sampler Result may hold the full request and response, it can contain passwords, access tokens, cookies, personal details and business data. A results file or a screenshot from the debugging window is therefore sensitive material, even if the test used only test accounts. The risk is real: result files are often attached to emails, uploaded to shared drives and pasted into tickets.

Protective habits

Mistakes that make the Sampler Results lie, or make you misread them.

A checklist you can apply tomorrow, and four stories that show it working.

Best-practice checklist

Real-world stories

The same record, filled in differently for databases, messages, sockets and scripts.

Most examples in this guide use web requests, but JMeter can test many other things: database queries, message queues, file transfers, directory services, raw network sockets and custom scripts. All of them create Sampler Results with the same set of fields. What changes is how each sampler fills those fields. Understanding these differences stops you from misreading results when you leave the world of web pages.

What to check when you leave HTTP

A results file is a small database. The value comes from the questions you ask it.

Once a test is finished, the results file holds the full story of the run in thousands or millions of rows. Standard reports answer the usual questions, but expert engineers go further. They slice the data by time, by label, by thread and by response code to answer sharper questions. The following ideas turn raw Sampler Results into real insight.

Slice by time

Group samples into small time buckets, such as every ten or thirty seconds, and calculate the percentiles, the error count and the throughput for each bucket. The result is a timeline that shows how the system behaved during the test, rather than one average for the whole run. Events such as garbage collection pauses, scheduled jobs, cache expiry and auto-scaling appear as spikes or steps on this timeline, and you can match them with server logs.

Slice by error type

Group failed samples by the full response code text and the failure message. A report that says “five percent errors” is far less useful than one that says “three percent connection timeouts, one percent service unavailable and one percent failed content checks”. Each type points to a different cause and a different owner.

Compare runs, not just numbers

The strongest use of results is comparison. Run the same test against the old and the new version and compare the percentiles per label. Make sure the settings are identical: the same thread counts, the same ramp-up, the same data and the same labels. A single run can be unlucky, because networks, caches and shared environments vary. Repeat important tests several times, and treat differences smaller than the natural variation between identical runs as noise.

Satisfaction scores

The HTML report includes a satisfaction score built from elapsed times, often called an Apdex score. It uses two thresholds: a lower one under which a response is called satisfying, and a higher one under which it is called tolerable. Responses above the higher threshold count as frustrating. The score combines these groups into a single number between zero and one. The thresholds are configurable, and you should set them to match what your business considers fast and acceptable, not leave the defaults without thinking.

flowchart TD
    A["Raw results file"] --> B["Clean: remove ramp phases and helper labels"]
    B --> C["Slice by time, label, thread and error type"]
    C --> D["Compare with a baseline run"]
    D --> E["Find the weak step and the load level where it breaks"]
    E --> F["Report with evidence and a clear recommendation"]
        

Beware of missing samples

Thread-based tests send the next request only after the previous one has finished. When the server stalls for ten seconds, every thread waits, and the requests that real users would have sent during that stall never appear in the results. The results therefore under-represent slow periods, and the percentiles look better than what real visitors would feel. This effect, known as coordinated omission, is a limitation of closed-loop tests. Be aware of it when you interpret tail percentiles, and consider rate-driven test designs when your real traffic arrives independently of server speed.

What a thread does after a failed sample, and how teams turn results into decisions.

What happens after a failed sample

When a Sampler Result is marked as failed, the thread group decides what the thread does next. The thread can carry on with the next step, start its next loop, stop itself, stop the whole test after finishing running requests, or stop the whole test immediately. This choice shapes the load and the shape of your results. If failing threads stop themselves, then during a failure storm the number of active threads falls, the pressure on the application drops, and the system may look as if it recovered when in fact your own load faded away. For capacity tests, most teams choose to continue or to start the next loop, so the load stays steady and the failures stay visible.

Designing realistic retries

Real users and real clients often retry a failed action. A mobile app may retry a failed call automatically, and a person may press the button again. You can copy this behaviour with a loop controller that repeats a step while the previous sample failed. JMeter keeps a thread variable that records whether the last sample succeeded, and a controller can read it to decide whether to retry. The important rule is to keep each attempt as its own Sampler Result with a clear label, so that your report shows both the failures and the retries, rather than hiding failures behind eventual success.

Using Sampler Results in automated gates

Many teams run short performance tests inside an automated delivery pipeline and use the results to decide whether a build may move forward. The test writes a results file, a small step reads it, calculates figures such as the ninety-fifth percentile per label and the error percent, and compares them with agreed limits. If a limit is broken, the pipeline stops. This turns performance from a once-a-quarter event into a daily guard.

Start from what you see in the results, and work toward the cause.

A calm way to investigate

Quick answers to questions that come up in almost every project.

The sampler is the element that performs the action. The Sampler Result is the record of one run of that action, with the timings, status, sizes and data. One sampler can produce thousands of results during a test.

Elapsed time runs from the start of the request to the last byte of the response. Latency runs from the start of the request to the first byte. The difference between them is roughly the time spent downloading the response.

Because an assertion judged the content or the time to be wrong. The failure message in the result explains which assertion failed and why. A normal status code only means the server answered, not that the answer was correct.

No. Timers run before the sampler starts measuring, so their delay is not part of the elapsed time of the sample. Idle time records such pauses separately, and a transaction controller can include them in a group total if you ask it to.

By default, JMeter does not save response data, headers or request data in the results file, to protect file size and memory. You can switch on saving for these fields, but do it only for debugging or for failed samples.

It means the request failed before a normal server answer was received, for example because of a refused connection, an unknown host, a timeout or a handshake failure. The text after it names the technical problem.

CSV is better for almost all load tests because it is compact, fast and works directly with the report generator. XML is useful for short debugging runs when you need full detail and nested sub-results.

Common reasons are that the extractor reads the wrong field, such as the body instead of the headers, that its scope excludes the sub-sample where the value appears, that the pattern does not match, or that the encoding is wrong. Check these in turn.

Use the thread name saved in each result. Group failed samples by thread name to see whether failures are spread across all users or concentrated in a few, which often points to bad test data.

Yes. Memory-hungry listeners, saved bodies and heavy assertions can starve the load generator and delay requests inside JMeter, so the measured times include delays that the application did not cause.

Usually the report should count the parent result, because counting both the parent and its children double-counts the same work. Know how your report treats sub-results before you compare tests.

Only if it is lean and has been checked. Files that contain request or response data may hold passwords, tokens and personal details. Clean or mask them first, and store files in protected locations.

The Sampler Result is the foundation of every JMeter report. It is the record created each time a sampler runs, and it carries the identity, the timings, the status, the sizes, the thread information, the request, the response and the verdicts of the assertions. Extractors and assertions read it during the test, listeners display and save it, and reports turn thousands of them into statistics. If the records are rich, correct and lean, then your report is trustworthy and your debugging is fast. If they are thin, misleading or heavy, the report can be wrong while looking perfectly professional.