Skip to content

Functions Usage

Since OctoPerf operates JMeter in the background, it is also possible to use JMeter functions. Functions are shortcuts you can use to avoid adding a script block into your virtual user. The same result can be achieved programmatically but they make life easier by handling a lof of common situations.

Note

The function name will be replaced by its output upon runtime in the same way a variable would be. Some functions do not output anything, refer to the function documentation for more details.

Information

__threadNum

This function outputs the thread (= virtual user) number. The number is between 1 and the max number of running threads. This value is not unique.

Typically In OctoPerf, every runtime group (and load generator in case a runtime group has more than one) will count thread numbers independently.

If you are looking for a unique value per thread, combine this with machineName.

Example

${__threadNum}

__iterationNum

This function returns the current iteration number for the virtual user. The iteration number indicates how many times the virtual user was able to execute all its actions starting at 1.

Example

${__iterationNum}

__threadGroupName

This function returns the name of the virtual user as specified on the design screen.

Example

${__threadGroupName}

__samplerName

This function returns the name of the current sampler. For example it can output the name of the HTTP request being executed.

Warning

This function only works when used from inside a sampler, post/pre processor or assertion.

Example

${__samplerName()}

The output can be saved into a variable in order to be reused later:

Example

${__samplerName(myvar)} ${myvar}

__machineIP

This function returns the local machine IP. In OctoPerf, the output will always be 172.17.0.2 since this is the local address of the docker container.

Example

${__machineIP}

__machineName

This function returns the local machine name. In OctoPerf, the output will be the local docker container Id, a string of 12 random characters that is unique to each docker container. As such this function can be used to keep track of each individual thread when combined with threadNum and iterationNum

Example

${__machineName}

__TestPlanName

This function returns the test plan name. In OctoPerf, the output will always be scenario.jmx since this is how we name all test plans.

Example

${__TestPlanName}

__log

This function logs a message and returns its input string.

Attribute Description Required
String to be logged The string you want to log Yes
Log level OUT, ERR, DEBUG, INFO (default), WARN or ERROR No
Throwable text Creates a Throwable to pass to the logger No
Comment Displayed in the string. Useful to identify what is being logged. No

Example

Simple log message

${__log(Message)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : Message

Log message using a variable (${myvar} = value)

${__log(${myvar},,,myvar=)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : myvar= value

__logn

This function logs a message but returns an empty string. It works the same way than log but can be used from anywhere since it has no output.

Attribute Description Required
String to be logged The string you want to log Yes
Log level OUT, ERR, DEBUG, INFO (default), WARN or ERROR No
Throwable text Creates a Throwable to pass to the logger No

Example

Simple log message

${__logn(Message)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : Message

Log message using a variable (${myvar} = value)

${__logn(myvar=${myvar})}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : myvar=value

File

__StringFromFile

This function returns a string from a file. Every time it is called it reads the next line. All virtual users running on the same OctoPerf load generator share access to this file, so they are guaranteed to get a different line, provided there are enough lines.

Attribute Description Required
File name Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in resources/. Yes
Variable name Variable in which the value will be stored for later use. No
Start sequence number In case of multiple files specify the starting sequence number. No
End sequence number Final sequence number. If omitted there is no limit. No

Warning

Multiple calls to this function will open the file independently and might result in different values being used. If you need to reuse the value, make sure to save it to a variable.

Example

Read from multiple files

${__StringFromFile(resources/file#'.'log,,1,2)}

file1.log, file2.log

Read the same file twice

${__StringFromFile(resources/file.log,,,2)}

file.log is read twice

__FileToString

This function returns the content of an entire file as a string. Every time it is called it reads the entire file.

Attribute Description Required
File name Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in resources/. Yes
File encoding Default encoding is iso 8859-1, use this option to change it for instance to UTF-8 No
Variable name Variable in which the value will be stored for later use. No

Example

${__FileToString(resources/file.log,UTF-8)}

__XPath

This function returns the result of an XPath expression applied on an XML file. Upon each call to the function, the next available match will be returned, at the end of the file it loops back to the start. If there is no match an empty string is returned.

Since this works similarly to the XPath processor, we recommend to use it instead because it is natively integrated in OctoPerf's UI.

Attribute Description Required
File name Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in resources/. Yes
XPath Default encoding is iso 8859-1, use this option to change it for instance to UTF-8 Yes

Warning

This function will load the entire file in memory in order to apply the XPath expression. On large files this can lead to huge memory consumption.

Example

${__XPath(resources/file.xml, //target/@name)}

__StringToFile

This function appends or overwrites a file with a string.

Attribute Description Required
File name Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in resources/. Yes
String The string to write. Yes
Append? TRUE to append the string at the end of the file, FALSE to overwrite the content of the file. Defaults to TRUE No
File encoding Default encoding is iso 8859-1, use this option to change it for instance to UTF-8 No

Example

${__StringToFile(resources/file.log,message)}

__CSVRead

This function reads columns from a CSV file. Compared to __StringFromFile it allows you to pick the right comma separated values instead of a whole line. Since the CSV variable already does this in a more efficient way, we strongly recommend using it instead.

Attribute Description Required
File name Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in resources/. Yes
Column number Column number starting from 0. Use NEXT to skip to the next line and return an empty string. Yes

Example

${__CSVRead(path/name.csv,0)} Check out our more advanced example on the CSV variable page for more details.

Time

__time

This function returns the current time in various formats.

Attribute Description Required
Format The date output format, see DateTimeFormatter documentation for more details. Yes
Variable name Variable in which the value will be stored for later use. No

Some examples with the current date 2021-02-10 13:31:16 :

Time Result
${__time()} 1612960276007
${__time(/1000)} 1612960276
${__time(y-MM-dd HH:mm:ss)} 2021-02-10 13:31:16
${__time(YMD)} 20210210
${__time(Y-M-D--H:M:S)} 2021-02-10--14:32:16

__timeshift

The Timeshift function can generate date and times as well but is mostly used to place an offset on a date.

Attribute Description
Format The date output format, see DateTimeFormatter documentation for more details.
Date to shift The date you want to shift using Format set in first attribute. If empty, current date is used instead.
Shift value Indicates the amount of time to shift. The format is PnDTnHnMn.nS it can be preceded by a - for negative date shifts. More info can be found in the documentation.
Locale to use for format The string format of a locale. See the locale documentation for more info. If empty, the function will default toen_EN.
Variable name Variable in which the value will be stored for later use.

Warning

Contrary to what Oracle's documentation may suggest, to use negative date increments for time intervals of an hour or less, it is mandatory to use PT instead of just P. Ex: -PT1H.

Some examples with the current date 2021-02-10 13:31:16 :

Timeshift Result
${__timeShift(,,,,)} 1612960276007
${__timeShift(dd/MM/yyyy,,,,)} 10/02/2021
${__timeShift(y-MM-dd HH:mm:ss,,,,)} 2021-02-10 13:31:16
${__timeShift(dd/MM/yyyy,,P1D,,)} 11/02/2021
${__timeShift(dd-MM-y-HH-mm-ss,,P1DT1H1M,,)} 11-02-2021-14-32-16
${__timeShift(dd-MM-y-HH-mm-ss,,-PT1H,,)} 10-02-2021-12-31-16
${__timeShift(y MMM dd HH:mm:ss,,,fr_FR,)} 2021 févr. 10 13:31:16

__dateTimeConvert

This function returns a date converted from its source format to a destination format of your choice.

Attribute Description Required
Date string The date string to convert. Yes
Source format The Date string format, if omitted it must be an epoch. No
Target format The destination format, see DateTimeFormatter documentation for more details. Yes
Variable name Variable in which the value will be stored for later use. No

Example

${__dateTimeConvert(2021-02-10,yyyy-MM-dd,dd/MM/yyyy)} outputs 10/02/2021

Compute

__Counter

This function returns an incrementing integer. The value is incremented every time a virtual user finishes its iteration. Calling this function several times within the same iteration will yeld the same value.

Depending on your use case, you might have better control on the counter through the Counter variable.

Attribute Description Required
Local? TRUE means the counter is local to the current thread/Virtual user only. FALSE means it will increment with every thread/Virtual user running inside the same OctoPerf container. Yes
Variable name Variable in which the value will be stored for later use. No

Example

${__counter(TRUE,count)}

__digest

This function returns an encrypted value based on the hash, salt and other parameters.

Attribute Description Required
Algorithm MD2, MD5, SHA-1, SHA-224, SHA-256, SHA-384 or SHA-512. For more details check StandardNames. Yes
String to encode The value that will be encrypted. Yes
Salt Salt to be added after the string. No
Upper Case Results will be lowercase, use TRUE to uppercase results. No
Variable name Variable in which the value will be stored for later use. No

Example

${__digest(SHA-512,This is a value to encrypt,salt,,)}

__intSum

This function returns the sum of two or more integer values.

Attribute Description Required
First integer The first integer to add. Yes
Second integer Second integer to add. Yes
Nth integer Nth integer to add. No
Variable name Variable in which the value will be stored for later use. Must contain at least one non-integer char. No

Example

${__intSum(14,6,22,myvar)}

__longSum

This function returns the sum of two or more long values. Use this when __intSum isn't enough.

Attribute Description Required
First integer The first long to add. Yes
Second integer Second long to add. Yes
Nth integer Nth long to add. No
Variable name Variable in which the value will be stored for later use. Must contain at least one non-integer char. No

Example

${__longSum(14,6,22,myvar)}

__doubleSum

This function returns the sum of two or more floating values.

Attribute Description Required
First value The first double to add. Yes
Second value Second double to add. Yes
Nth value Nth double to add. No
Variable name Variable in which the value will be stored for later use. Must contain at least one non-float char. No

Example

${__doubleSum(14.2,5.7,22.1,myvar)}

__Random

This function returns a random value between min and max.

Attribute Description Required
Min Minimum value. Yes
Max Maximum value. Yes
Variable name Variable in which the value will be stored for later use. No

Example

${__Random(0,10, variable)}

__RandomDate

This function returns a random date between the start and end date.

Attribute Description Required
Format The date output format, see DateTimeFormatter documentation for more details. No
Start Start date, default is now. No
End End date. Yes
Locale The locale to be used. See locale list for more details. Default is en_EN. No
Variable name Variable in which the value will be stored for later use. No

Example

${__RandomDate(,,2025-12-31)} ${__RandomDate(yyyy MM dd,,31 12 2025,,variable)}

__RandomFromMultipleVars

This function returns a random value based on all the variables provided.

Attribute Description Required
Source variables Pipe separated list of variables names. Yes
Variable name Variable in which the value will be stored for later use. No

Example

${__RandomFromMultipleVars(variable1|variable2)}

__RandomString

This function returns a random string.

Attribute Description Required
Length Length of the random string. Yes
Allowed chars List of allowed characters. No
Variable name Variable in which the value will be stored for later use. No

Example

${__RandomString(6,a12zeczclk, MYVAR)}

__chooseRandom

This function returns a random value picked among its arguments. The last argument must be the variable name in which the random value is stored.

Attribute Description Required
1st value First random candidate. Yes
2nd value Second random candidate. No
Nth value Nth random candidate. No
Variable name Variable in which the value will be stored for later use. Yes

Example

${__chooseRandom(red,green,blue,orange,violet,magenta,randomColor)}

__UUID

This function returns a random Universally Unique IDentifier.

Example

${__UUID}

__if

This function returns two different values depending on the comparison of its two first arguments.

Attribute Description Required
Actual value Value to be compared. Yes
Expected value Value to compare with. Yes
Return if true Value returned if comparison is == Yes
Return if false Value to return if comparison is != Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__if(${number}, 5, ok, invalid)}

Properties

__isPropDefined

This function returns TRUE if the property exists or FALSE if it doesn't.

Example

${__isPropDefined(TESTSTART.MS)}

__property

This function returns the value of a property. The shorter __P function can also be used, although it can't be stored into a variable (2nd attribute is default value instead).

Properties are values shared among all users running inside the same OctoPerf container. This can be used in combination with the runtime properties to control your scripts in real time while the test is running.

Attribute Description Required
Name Name of the property to fetch. Yes
Variable name Variable in which the result will be stored for later use. No
Default value If the property doesn't exist, return this value instead. No

Example

${__property(propertyName,myvar)}

${__P(propertyName)}

__setProperty

This function returns the value to be set or an empty string. It can be used to update the value of a property.

Attribute Description Required
Name Override or create a property with this name. Yes
Value Value to set. Yes
Return TRUE if the value should be returned as well, defaults to FALSE. No

Example

${__setProperty(propertyName,propertyValue)}

__env

This function returns the value of an environment variable.

Attribute Description Required
Name Name of the environment variable to fetch. Yes
Variable name Variable in which the result will be stored for later use. No
Default value If the environment variable doesn't exist, return this value instead. No

Example

${__env(env_var,myvar)}

Scripting

__groovy

This function returns the output of a groovy script.

It is sometime required to use a scripting language to deal with unusual behaviors. Although it is possible to write JSR samplers/pre/postprocessors it is sometimes faster to just go for a quick one line script just where it is required.

Attribute Description Required
Expression Groovy expression to evaluate. Yes
Variable name Variable in which the result will be stored for later use. No

Example

It can be as easy as a simple condition for your while/if:

${__groovy(${count}<=2)}

Or you could compute a value:

${__groovy(vars.get("myVar").substring(0\,2))}

Info

If you make use of groovy, avoid using the ${...} syntax for variables. Otherwise since the result may differ on each execution your script cannot be cached and may result in poor performance.

__javaScript

This function returns the output of a JavaScript script.

It is sometime required to use a scripting language to deal with unusual behaviors. Although it is possible to write JSR samplers/pre/postprocessors it is sometimes faster to just go for a quick one line script just where it is required.

Attribute Description Required
Expression JavaScript expression to evaluate. Yes
Variable name Variable in which the result will be stored for later use. No

Example

It can be as easy as a simple condition for your while/if:

${__javaScript(${count}<=2)}

Or you could compute a value:

${__javaScript(${myvar}.slice(7\,15))}

Variables

__split

This function returns the value of the string passed as a first attribute. It stores the splits of this string in a list of variables.

Attribute Description Required
Name Name of the string to split. Yes
Variable name Variable in which the result will be stored for later use. If several splits, _N will be added at the end of the variable name. Yes
Delimiter The delimiter. Default is , (comma) No

Example

If myvar contains this|is|a|list|42, with:

${__split(${myvar},split,|)}

The output variables will be:


​ * split_n = 5 ​ * split_1 = this ​ * split_2 = is ​ * split_3 = a ​ * split_4 = list ​ * split_5 = 42 ​ * split_6 = null ​ * etc...

__eval

This function returns the result of evaluating a string expression. This is especially useful when you need to evaluate the variables and functions from inside a string stored inside a variable.

Example

For example with the following variables:

  • name = "OctoPerf"
  • tool = "JMeter"
  • input = "${name} is ${tool} on steroids"

${__eval(${input})}

Will return: OctoPerf is JMeter on steroids

__evalVar

This function returns the result of evaluating a string expression. It works exactly as __eval but the variable syntax markers can be omitted.

Example

${__evalVar(input)}

__V

This function returns the result of evaluating a string expression. Since the ${...} syntax used for variables does not allow nested variables this function must be used to tell JMeter to evaluate nested variables. It works exactly as __eval.

Example

${__V(categories_${counter})}

We already have a detailed example of a situation where this can be useful on the while page.

__isVarDefined

This function returns TRUE if the variable name exists or FALSE if it doesn't.

Example

${__isVarDefined(myvar)}

__isDefined

This function returns 1 if the variable name exists or 0 if it doesn't.

Example

${__isDefined(myvar)}

String

__char

This function returns the result of evaluating a comma separated list of unicode codes.

The number to be converted to a Unicode character can be:

  • Decimal number by default,
  • Hex number, if prefixed by 0x,
  • Octal, if prefixed by 0.

Example

${__char(13,10)} will return CRLF

${__char(111,99,116,111,112,101,114,102)} will return octoperf

__changeCase

This function returns a string with changes to its case.

Attribute Description Required
String String to update. Yes
Case mode UPPER, LOWER or CAPITALIZE Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__changeCase(octoperf is JMeter on steroids,UPPER)} will return OCTOPERF IS JMETER ON STEROIDS

${__changeCase(octoperf is JMeter on steroids,LOWER)} will return octoperf is jmeter on steroids

${__changeCase(octoperf is JMeter on steroids,CAPITALIZE)} will return Octoperf Is JMeter On Steroids

__regexFunction

This function returns the result of a regex expression applied to the last response. It works similarly to the regex post processor and offer the same configuration options.

__strLen

This function returns the length of a string.

Attribute Description Required
String String to evaluate. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__strLen(${myvar})}

__substring

This function returns a subset of a string.

Attribute Description Required
String String to evaluate. Yes
Begin index Index of the first char of the substring (starting at 0). Yes
End index Index of the last char of the substring. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__substring("OctoPerf is JMeter on steroids",13,19)} will return JMeter.

__strReplace

This function returns a string after replacing a subset of it.

Attribute Description Required
String String to evaluate. Yes
Substring to replace The subset that will be replaced. All matches will be replaced from beginning to end. Yes
Replacement substring The string to replace with. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__strReplace("OctoPerf is JMeter on steroids",on,with)} will return OctoPerf is JMeter with steroids.

__strReplaceRegex

This function returns a string after replacing a subset of it through a regex.

Attribute Description Required
String String to evaluate. Yes
Search expression Regex that defines what to replace. Yes
Replacement substring The string to replace with. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__strReplaceRegex("OctoPerf is JMeter on steroids",' ',-)} will return OctoPerf-is-JMeter-on-steroids.

__MD5

This function returns the MD5 hash of a string.

Attribute Description Required
String String to hash. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__MD5("OctoPerf is JMeter on steroids")} will return fc1ddf979566cc0a07e94ba8a26d7e00.

__unescape

This function returns the result of evaluating a Java escaped string. It makes it easier to input special chars than using the UI.

Example

${ __unescape(\r\n)} will return CRLF.

__escapeHtml

This function returns a string and escapes the characters using HTML entities.

Example

${__escapeHtml("OctoPerf" & "JMeter")} will return &quot;OctoPerf&quot; &amp; &quot;JMeter&quot;.

__unescapeHtml

This function returns a string and unescapes the characters using HTML entities.

Example

${__unescapeHtml(&quot;OctoPerf&quot; &amp; &quot;JMeter&quot;)} will return "OctoPerf" & "JMeter".

__escapeOroRegexpChars

This function returns a string where ORO Regexp meta characters are escaped.

Example

${__escapeOroRegexpChars([^"].+?,)} will return \[\^\"\]\.\+\?.

__escapeXml

This function returns a string where characters are escaped using XML 1.0 entities.

Example

${__escapeXml(&quot;OctoPerf&quot; &amp; &quot;JMeter&quot;)} will return "OctoPerf" & "JMeter".

__urlencode

This function returns a string where URL chars have been encoded. Our correlation rules will use this function when encoding is set to Url encode.

Example

${__urlencode(string th@t requires "encoding")} will return string+th%40t+requires+%22encoding%22.

Info

Using this function spaces were encoded as +, if you prefer to have them encoded as %20 you can use another function like:

${__javaScript(encodeURIComponent("${query}"),)}

__urldecode

This function returns a string where URL chars have been decoded. Our correlation rules will use this function when encoding is set to Url decode.

Example

${__urldecode(string+th%40t+requires+%22encoding%22)} will return string th@t requires "encoding".

__base64Encode

This function returns a string encoded in base64.

Attribute Description Required
String String to encode. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__base64Encode("OctoPerf is JMeter on steroids")} will return T2N0b1BlcmYgaXMgSk1ldGVyIG9uIHN0ZXJvaWRz.

__base64Decode

This function returns a string decoded from a base64 value.

Attribute Description Required
String String to decode. Yes
Variable name Variable in which the result will be stored for later use. No

Example

${__base64Decode("T2N0b1BlcmYgaXMgSk1ldGVyIG9uIHN0ZXJvaWRz")} will return OctoPerf is JMeter on steroids.