A property is a named setting that belongs to the whole JMeter program.

Apache JMeter is a free, open-source tool from the Apache Software Foundation. It pretends to be many users at the same time and measures how a system behaves under that crowd. A JMeter test is described by a test plan, a tree of small building blocks called elements. JMeter itself, the program that runs the plan, also has settings, such as where to save results, how often to print progress, and which remote machines to use. Those settings are stored as properties.

The simple definition

A JMeter property is a named piece of text with a value, such as a name and a number. There is one shared set of properties for the whole running program. Every virtual user, which JMeter calls a thread, sees the same property values. Some properties control how JMeter itself behaves. Others are ones you invent, to feed values into your own plan.

Two kinds of properties

• Built-in properties have names that JMeter already understands, and they change how the program behaves.
• Custom properties have names you choose, such as a user count or a server name, and they only matter if your plan reads them.

To reference a property is to ask JMeter for its value at the right moment.

The phrase property reference has two meanings that beginners often mix up. In the narrow sense, it means writing a function inside your plan that reads a property, so that the plan picks up the current value when it runs. In the wide sense, it means the whole body of knowledge about properties: where they come from, what they are called, and how to use them. This guide covers both.

Why a reference and not a fixed value

If you type a fixed number into a field, the number is frozen inside the plan. If you instead write a reference, the plan asks JMeter for the value each time the plan starts, or each time the element runs. The plan stays the same while the value changes from run to run, depending on what you passed in from outside.

They look similar and they behave very differently.

A variable in JMeter is a named value that belongs to one virtual user. You read it by writing its name inside a dollar sign and curly brackets. A property belongs to the whole program. Mixing them up is the most common beginner mistake, so it is worth slowing down here.

A simple rule to remember

Ask who needs the value. If it is one user’s personal data, use a variable. If it is a setting for the whole test, use a property. Following this rule early prevents a whole family of bugs that appear only when many users run together.

Several sources feed one shared set, and they are applied in a sequence.

When JMeter starts, it builds its set of properties from several places. First it reads its main property file. Then it reads a second file meant for your own overrides. Then it applies any extra files you named, and finally the options you typed on the command line. Each later source can replace what an earlier one set.

flowchart TD
    A["Built-in defaults inside JMeter"] --> B["jmeter.properties in the bin folder"]
    B --> C["user.properties in the bin folder"]
    C --> D["Extra property files named at start-up"]
    D --> E["Command-line options for properties"]
    E --> F["Final set of properties used by the running test"]
    F --> G["Functions in the plan read values from this set"]
    G --> H["Scripts can also read and change the set while running"]

Why layers help

• The shipped file stays untouched, so upgrading JMeter never destroys your changes.
• Your team can share one overrides file under version control.
• A pipeline can add one-off values without editing any file.

The main settings file, read carefully and rarely edited.

JMeter ships with a long file named jmeter.properties, found in the bin folder of the installation. It lists hundreds of settings, almost all of them commented out and accompanied by plain explanations. It is the closest thing JMeter has to a built-in reference manual for its own behaviour, and reading through it once is time well spent.

How the file looks

Each setting is a name, an equals sign, and a value, on one line. Lines that begin with a hash sign are comments and are ignored. A commented-out line usually shows the default value, so you can see what JMeter does when you say nothing.

The file made for your own changes.

Next to the main file sits a second, usually near-empty file called user.properties. JMeter reads it after the main file, so any setting you place there replaces the default. It is the officially intended place for local customisation, and it survives upgrades far more easily than edits to the main file.

What belongs in it

• Settings that you want for every test run on this machine.
• Changes to results-saving behaviour, such as which fields are written to a result file.
• Settings for remote machines in a distributed test, such as the list of worker addresses.
• Your own custom properties, with a clear naming prefix.

What does not belong in it

• Values that change from run to run, such as the number of users in today’s experiment. Those fit better on the command line.
• Passwords and tokens. Files can be copied and read by many people.

JMeter also has access to settings of the Java platform it runs on.

JMeter is written in Java, and the Java platform has its own idea of properties, called system properties. They describe the environment: the operating system name, the user’s home folder, the character encoding, and settings for network security. A separate file, usually named system.properties in the bin folder, can hold values that are passed to the Java platform when JMeter starts. A command-line option can set individual system properties too.

Why the difference matters

A beginner may try to read a system property using the function made for JMeter properties, and be surprised to get nothing back. The two sets are separate. Scripts can reach both. When something is not found, check that you are looking in the right set.

A handful of short flags put properties exactly where you need them.

When you start JMeter from a command line, you can pass options that set properties for that run only. This is the most flexible method, because the values come from the outside and nothing on disk changes. The table lists the main ones. Always confirm the details with the help text of your own version.

A habit worth building

Prefer the command line for anything that changes between runs. Prefer files for anything that stays the same for a machine or an environment. Prefer the plan itself for anything that is truly part of the test design.

Later sources override earlier ones, and the command line is usually last.

Because the same property can appear in several places, JMeter needs a rule for which value wins. The general rule is that values applied later replace values applied earlier. In practice the command line has the final say, and the built-in defaults have the least.

A clear diagnostic habit

When a property has an unexpected value, check from the strongest source to the weakest: first the command line, then the extra files, then the overrides file, and last the main file. The first place where the name appears is almost always the answer.

The most used property function reads a value and supplies a default.

JMeter has built-in functions, small helpers whose names start with two underscores, that you can write inside many fields of a plan. The function named __P reads a property. You give it the property name and, after a comma, a default value to use when the property is not set. The whole thing is wrapped in a dollar sign and curly brackets, like a variable reference, so JMeter knows to evaluate it.

The three parts

Why a default is not optional in practice

• It lets the plan run in the graphical window with no extra setup.
• It documents the normal value for anyone who opens the plan.
• It prevents a missing value from silently becoming something surprising.

A longer cousin that can also copy the value into a variable.

Besides __P, JMeter offers a function named __property. It also reads a property by name, and it accepts a default, but it has an extra optional part: the name of a variable. When you give a variable name, the function stores the value there as well, so later parts of the plan can read it as an ordinary variable.

When to choose which

• Use __P for simple one-off reads, such as a thread count in a single field.
• Use __property when you want to read once and reuse the value many times as a variable.

Properties can also be changed from inside a plan, but this needs care.

The function __setProperty changes a property while the test is running. You give it a name and a new value. By default it returns nothing visible, and an optional extra part lets it return the old value instead. Scripts can do the same through a ready-made object that gives access to the property set.

Why anyone would do this

• To share one result computed by a single thread, such as a token fetched once for the whole test.
• To switch the behaviour of the plan part-way through, for example moving from a warm-up phase to a measured phase.
• To pass a value from a setup stage to the main part of the test.

Why it is risky

Properties are shared by every thread. A change made by one thread is seen by all the others immediately. If many threads set the same property at the same time, their writes can overwrite each other, and the order is not predictable. A property set in one place and read in another can also produce results that depend on timing, which makes tests hard to repeat.

Every property is text, and the receiver decides how to read it.

Properties have no types. Whatever you write, JMeter stores it as text. The element or function that reads the property decides how to interpret it. A field that expects a number will convert the text. A setting that expects a true or false will check for particular words.

Habits that prevent confusion

• Put the unit in the name, such as a name ending in seconds or milliseconds.
• Avoid spaces around values, since they become part of the text.
• Document the expected form beside each property in your overrides file.

Common settings that are better supplied from outside the plan.

Almost any text or number field in a plan can accept a property reference. The table lists the settings that teams most often move out of the plan.

Read each property once at the top, and use clean variable names everywhere else.

A tidy pattern is to place a User Defined Variables element near the top of the plan. In its table, each row holds a variable name and a value, and the value can be a property reference with a default. The rest of the plan then uses ordinary variable references, and never mentions properties at all.

Benefits of this pattern

Things to watch

• Variables defined this way are evaluated when the test starts, so they reflect the property values at that time.
• Where you place the element in the tree affects its scope, so put it at the top of the plan if it should apply everywhere.
• Values derived from a property that changes at run time will not follow the change automatically.

Script elements get ready-made objects for both worlds.

JMeter’s script elements, such as the JSR223 elements, are given a few ready-made helpers without you having to ask. One helper gives access to the thread’s variables, and another gives access to the program-wide properties. Others give access to the current sample, the log, and the context of the running test. Knowing the difference in names saves a lot of confusion.

Simple rules for scripts

• Read properties freely, because reading is safe.
• Write properties rarely, and only at planned moments.
• Remember that properties are text, so convert to numbers deliberately.
• Prefer variables for anything that belongs to one user.

Files and flags are merged once, and functions read the result.

Understanding the internal path removes most of the mystery. At start-up, JMeter reads the files and the command line and merges everything into one shared table of names and values. After that, any element, function, or script that asks for a property reads from that single table.

sequenceDiagram
    participant U as User or Pipeline
    participant J as JMeter Start-up
    participant F as Property Files
    participant T as Shared Property Table
    participant P as Test Plan Function
    participant S as Server Under Test
    U->>J: Start with options
    J->>F: Read jmeter.properties then user.properties
    F-->>J: Names and values
    J->>T: Merge files and command-line values
    T-->>J: Final table ready
    J->>P: Run the plan
    P->>T: Ask for a property by name
    T-->>P: Value or default
    P->>S: Send request using that value

Timing decides whether a change takes effect.

There are two moments to think about. The first is start-up, when files and command-line options fill the shared table. The second is evaluation, when a function in the plan asks for a value. Many fields are evaluated at the start of the test, while others are evaluated each time the element runs.

Graphical window and command line

In the graphical window, property references use their defaults unless you started the program with options. A plan that behaves one way when you press play in the window and another way in an automated run is usually showing the difference between defaults and supplied values. Always check which values are in effect.

Remote workers need their own copies of the values.

In distributed testing, a controller directs several worker machines, each running the same plan. Each worker is a separate JMeter program with its own property table. A property passed to the controller with the local option is invisible to the workers. The global option sends the value to the remote workers as well.

flowchart LR
    CMD["Command line with local and global options"] --> CTRL["Controller JMeter"]
    CTRL --> LP["Controller property table: local and global values"]
    CTRL -->|"global values sent"| W1["Worker 1 table"]
    CTRL -->|"global values sent"| W2["Worker 2 table"]
    CTRL -->|"global values sent"| W3["Worker 3 table"]
    LP -.->|"local values stay here"| CTRL
    W1 --> SUT["System under test"]
    W2 --> SUT
    W3 --> SUT

A classic surprise

A plan that reads its thread count from a property will happily use its default on every worker if the value never reached them. The test then runs with a very different load from what you intended, without any error message. When a distributed test behaves oddly, check what each worker actually received.

Pipelines depend on properties to run the same plan with different settings.

Many teams run load tests automatically inside build and release pipelines. A pipeline starts JMeter in non-GUI mode, with no window, and passes in the settings for that run. Property references make this possible, because nobody opens the plan to edit it.

A typical sequence

Keep a small property file for each environment and choose one at start-up.

Real systems live in several environments: a developer’s machine, a shared test environment, a staging environment that mimics production, and sometimes others. A good test plan runs against any of them without changes. Per-environment property files make this clean.

flowchart TD
    PLAN["One test plan with property references"] --> RUN["Start JMeter"]
    DEV["File: dev settings"] -.-> RUN
    TST["File: test settings"] -.-> RUN
    STG["File: staging settings"] -.-> RUN
    RUN --> PICK{"Which file was passed at start-up?"}
    PICK -->|"dev"| D1["Small load, local server"]
    PICK -->|"test"| D2["Moderate load, shared server"]
    PICK -->|"staging"| D3["Full load, production-like server"]

What goes in each file

• The server name, port, and protocol of that environment.
• The size of the test: user count, ramp-up, and duration suited to that environment.
• Locations of data files, if they differ.
• Switches that turn optional parts of the journey on or off.

The shipped file is large, but the names fall into a few families.

JMeter’s built-in properties tend to share prefixes that tell you what they control. Learning the families helps you search the main file quickly. The exact names and defaults depend on your version, so use this table as a map and open the file for the details.

A family of settings decides what ends up in your results file.

Every sample in a JMeter run produces a lot of information: the time, the label, the response code, the success flag, the number of bytes, the thread name, and much more. A group of properties decides which of these fields are saved into the result file, which is often called a JTL file, short for JMeter test log. The file usually uses the CSV format, a plain text table with comma-separated columns, though other formats exist.

The trade-off in plain words

Why this is a property question

Because these settings are properties, you can keep a lean setting for big runs and a detailed one for debugging, and switch between them with a file or a command-line option. The plan itself never changes.

The HTML dashboard report is tuned through properties too.

JMeter can turn a results file into a full HTML dashboard report, a small website with tables and charts. The look and content of this report are controlled by a family of properties. They decide which charts to show, how time is grouped, which response time thresholds count as satisfied or tolerated, and which requests to include or leave out.

Typical things teams tune

• The thresholds that define good, acceptable, and poor response times, used in the satisfaction score.
• The size of the time slices used in over-time charts.
• Which transactions or labels to include or exclude from summaries.
• The title and branding shown on the report pages.

A caution about moving the goalposts

Changing a threshold changes how results look without changing how the system behaved. If two teams compare reports built with different thresholds, they are comparing apples with oranges. Agree on the thresholds in advance, keep them in a shared file, and record them with each run.

Good names prevent collisions and confusion.

Because there is one shared table, a custom property name must not clash with a built-in one. Choosing a clear, consistent naming style keeps your properties separate from JMeter’s and easy for others to recognise.

Naming habits that work

One table is shared by many threads, so care is needed when writing.

Reading from the shared table is safe, since many threads can read the same value at once. Writing is where trouble begins. When two threads change the same property, the last writer wins, and the order depends on timing. Even a simple counter kept in a property can lose updates, because two threads may read the same old value and both write back the same new one.

Safer alternatives

• Use the built-in Counter element for numbers that increase.
• Use per-thread variables for anything personal to one user.
• Use a setup stage to compute shared values before the main threads start.

When a value surprises you, look at what JMeter actually holds.

Most property problems are really “which value is in effect?” problems. A few simple tools answer that question quickly.

A calm routine

Reading a property is cheap, but habits around it can add up.

A single property lookup takes almost no time. The cost comes from how many lookups happen and from what surrounds them. In a test with thousands of threads, small costs multiply. Here are the places where property use can quietly slow a load generator.

A result is only meaningful if you know the settings that produced it.

Imagine finding a results file from last month with no record of how many users were used, which server was targeted, or which thresholds applied. The numbers would be nearly useless. Properties are the settings of a run, so recording them alongside the results turns the numbers into evidence.

flowchart LR
    PIPE["Pipeline or tester"] --> CMD["Exact command with property options"]
    CMD --> RUN["JMeter run"]
    PF["Property files used"] --> RUN
    RUN --> RF["Results file"]
    RUN --> LOG["JMeter log"]
    CMD --> ARC["Archive folder"]
    PF --> ARC
    RF --> ARC
    LOG --> ARC
    ARC --> REP["Report and review"]

What to keep with every run

• The exact start-up command, including all property options.
• Copies of every property file used.
• The version of JMeter and of the test plan.
• The date, time, and target environment.
• The results file, the log file, and the report.

Properties are convenient, and convenience is how secrets leak.

Passwords, tokens, and keys often end up in properties because it is easy to do. But property files are plain text, they get copied, and they get committed to shared storage. Command-line options can be seen by other users on the same machine, and pipelines often print commands into logs that many people can read.

Specific risks

• Secrets in files: a password committed to shared storage may stay in its history forever.
• Secrets on the command line: they can appear in process lists and in build logs.
• Result files: if detailed saving is on, headers and bodies may contain tokens and personal data.
• Wrong target: a mistyped server name could send heavy load to a system you are not allowed to test.

Properties make plans flexible, and flexibility has a price.

Good habits repeat across good test plans.

A pattern called “Declare, Default, Document, Display”

Some habits look practical and cause pain later.

A dial that has never been turned is only a hope.

When you replace a fixed value with a property reference, the plan still looks the same on screen, and it is easy to believe it works. The only way to be sure is to turn each dial and watch what happens. A short routine takes minutes and prevents long, expensive mistakes.

Most problems come from a small set of causes. Match your symptom with the table.

A method for any puzzle

Follow an imaginary shop’s team as they use one plan for three goals.

A team tests an online shop. They have one plan with a settings table at the top. The table reads these properties: the server name, the number of users, the ramp-up time, the duration, and a switch that turns the payment step on or off. Every property has a small, safe default.

flowchart TD
    PLAN["One plan with a settings table at the top"] --> A["Smoke run: defaults, few users, short"]
    PLAN --> B["Load run: test environment file, many users"]
    PLAN --> C["Soak run: staging file, long duration, payment on"]
    A --> RA["Result and archive folder A"]
    B --> RB["Result and archive folder B"]
    C --> RC["Result and archive folder C"]
    RA --> CMP["Compare: same plan, different settings"]
    RB --> CMP
    RC --> CMP

What makes this setup healthy

• The plan has one settings table, so the dials are easy to see.
• Defaults are small and safe, so an accidental start does little harm.
• Environments are chosen by file, not by editing the plan.
• Every run leaves a complete record of the settings used.

Six ideas that beginners often get wrong.

A habit that corrects all six

Before relying on a property, ask three questions. Where is the value set, and in what order do the sources apply? Who reads it, and when? What will I see if the name is wrong? Honest answers to those three questions expose most misunderstandings before they cost you a run.

A short checklist to carry into your next test.

Common mistakes in one list

• Keeping per-user data in shared properties
• Leaving out defaults and getting a surprising value of one
• Misspelling names and not noticing the fallback
• Mixing seconds and milliseconds
• Assuming the controller’s values reach the workers
• Editing property files and expecting a running test to change
• Putting passwords in shared files or visible command lines
• Writing properties from every thread
• Forgetting to record which settings produced a result

Five typical situations, described in general terms so you can adapt them.

The file format is simple, and small slips cause quiet trouble.

A property file is plain text with one setting per line. Each line has a name, an equals sign, and a value. Lines that begin with a hash sign are comments. Blank lines are ignored. This simplicity is a strength, but it also means the file will happily accept a mistake and say nothing about it.

Rules worth remembering

• Spelling is exact. A name with a different capital letter, an extra space, or a missing dot is a different name.
• Trailing spaces can stay. Some editors leave invisible spaces at the end of a line, and those spaces may become part of the value.
• Paths need care. A backslash often has a special meaning inside property files, so many teams use forward slashes even on systems that prefer backslashes.
• Later lines win. If the same name appears twice in one file, the lower line normally replaces the upper one.
• Comments are free. Use them generously to explain the unit, the allowed values, and the reason for each setting.

Three dials shape the load, and they depend on each other.

The three most common properties in any plan describe the shape of the load. The number of users says how many virtual users run at the same time. The ramp-up period says how long JMeter takes to start all of them. The duration says how long the test runs in total. Changing one without thinking about the others is a classic mistake.

A small example with numbers

Suppose you ask for sixty users with a ramp-up of sixty seconds. JMeter starts roughly one new user every second. Now suppose you raise the users to six hundred but forget the ramp-up. Ten new users start every second, which is a much steeper climb, and the system may struggle before the full load is even reached. The test would then measure the shock of a sudden arrival more than the steady state.

Pipelines and containers keep settings in their own places, and a small bridge carries them in.

Build systems and servers usually store their settings as environment variables, which are named values kept by the operating system for every program started in that session. JMeter properties are a different thing. A pipeline therefore acts as a bridge: it reads the environment variables and turns them into command-line options for JMeter.

Why it helps

• The plan never needs to know which pipeline runs it.
• The same plan runs from a laptop, a build server, or a container.
• Secrets can stay in the pipeline’s protected storage until the last moment.

Properties are what let one test travel between machines.

Teams often run JMeter in many places: on a developer’s laptop while building the script, inside a container, which is a lightweight, self-contained package that carries a program and its settings, and on shared build servers. A plan with fixed values tends to break when it moves, because paths, addresses, and sizes differ. A plan built on property references moves easily, because only the supplied values change.

What to avoid

• Fixed absolute file paths inside the plan, which break on any other machine.
• Assuming a particular operating system’s folder style.
• Hidden settings that exist only on one person’s machine.

The terms of this guide in one place, each explained in a sentence.

Words that are easy to mix up

• Property and variable: shared by everyone versus private to one user.
• Local and global: stays on this program versus also reaches the workers.
• JMeter property and system property: two different sets with two different ways of being read.
• Default and override: the fallback inside the plan versus the value supplied from outside.

A one-page summary you can keep next to your test plan.

Five questions before pressing start

• Does every property reference have a safe default?
• Do I know which source supplies each effective value?
• For distributed runs, did every worker receive what it needs?
• Are units clear, and are secrets protected?
• Will the command and property files be archived with the results?

Quick answers to the questions beginners ask most often.

Properties are the dials of a JMeter test. They keep settings outside the plan, so one plan can run small or large, on any environment, from a window or from a pipeline, without being edited. They come from layered sources in a clear order, they are read through simple functions, and they are shared by every thread. Used well, they make tests repeatable and reviewable. Used carelessly, they hide silent fallbacks, create shared-state bugs, and leak secrets. If you remember one idea, let it be this: give every dial a safe default, make the effective values visible, and record the settings with every result.