httpRequest

Issues a HTTP request and registers handlers for the response.

Issues a HTTP request and registers handlers for the response.

PropertyTypeDescription
authorityStringHTTP authority (host:port) this request should target. Must match one of the entries in http section. The string can use string interpolation.
authority (alternative)BuilderHTTP authority (host:port) this request should target. Must match one of the entries in http section.
bodyBuilderHTTP request body.
body (alternative)StringHTTP request body (possibly a pattern).
compensationBuilderConfigures additional metric compensated for coordinated omission.
compressionBuilderConfigure response compression.
compression (alternative)StringRequest server to respond with compressed entity using specified content encoding.
CONNECTStringIssue HTTP CONNECT request to given path. This can be a pattern.
CONNECT (alternative)BuilderIssue HTTP CONNECT request to given path.
DELETEStringIssue HTTP DELETE request to given path. This can be a pattern.
DELETE (alternative)BuilderIssue HTTP DELETE request to given path.
endpointBuilderHTTP endpoint this request should target. Must match to the name of the entries in http section.
GETStringIssue HTTP GET request to given path. This can be a pattern.
GET (alternative)BuilderIssue HTTP GET request to given path.
handlerBuilderHTTP response handlers.
HEADStringIssue HTTP HEAD request to given path. This can be a pattern.
HEAD (alternative)BuilderIssue HTTP HEAD request to given path.
headersBuilderHTTP headers sent in the request.
methodenumHTTP method used for the request.
Options:
  • GET
  • HEAD
  • POST
  • PUT
  • DELETE
  • OPTIONS
  • PATCH
  • TRACE
  • CONNECT
metricStringRequests statistics will use this metric name.
metric (alternative)<list of strings>Allows categorizing request statistics into metrics based on the request path.
OPTIONSStringIssue HTTP OPTIONS request to given path. This can be a pattern.
OPTIONS (alternative)BuilderIssue HTTP OPTIONS request to given path.
PATCHStringIssue HTTP PATCH request to given path. This can be a pattern.
PATCH (alternative)BuilderIssue HTTP PATCH request to given path.
pathStringHTTP path (absolute or relative), including query and fragment. The string can use string interpolation.
path (alternative)BuilderHTTP path (absolute or relative), including query and fragment.
POSTStringIssue HTTP POST request to given path. This can be a pattern.
POST (alternative)BuilderIssue HTTP POST request to given path.
PUTStringIssue HTTP PUT request to given path. This can be a pattern.
PUT (alternative)BuilderIssue HTTP PUT request to given path.
slaBuilderList of SLAs the requests are subject to.
syncbooleanThis request is synchronous; execution of the sequence does not continue until the full response is received. If this step is executed from multiple parallel instances of this sequence the progress of all sequences is blocked until there is a request in flight without response.

Default is true.

timeoutStringRequest timeout - after this time the request will be marked as failed and connection will be closed.

Defaults to value set globally in http section.

TRACEStringIssue HTTP TRACE request to given path. This can be a pattern.
TRACE (alternative)BuilderIssue HTTP TRACE request to given path.

authority

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

body

Allows building HTTP request body from session variables.

PropertyTypeDescription
formBuilderBuild form as if we were sending the request using HTML form. This option automatically adds Content-Type: application/x-www-form-urlencoded to the request headers.
fromFileStringSend contents of the file. Note that this method does NOT set content-type automatically.
fromVarStringUse variable content as request body.
patternStringPattern replacing ${sessionvar} with variable contents in a string.
textStringString sent as-is.

body.form

PropertyTypeDescription
<list of mappings><list of builders>Add input pair described in the mapping.

body.form.<list of mappings>

Form element (e.g. as if coming from an INPUT field).

PropertyTypeDescription
fromVarStringInput field value from session variable.
nameStringInput field name.
patternStringInput field value replacing session variables in a pattern, e.g. foo${myvariable}var
valueStringInput field value (verbatim).

compensation

PropertyTypeDescription
metricStringMetric name for the compensated results.
metric (alternative)<list of strings>Configure a custom metric for the compensated results.
targetRatedoubleDesired rate of new virtual users per second. This is similar to constantRate.usersPerSec phase settings but works closer to legacy benchmark drivers by fixing the concurrency.
targetRate (alternative)BuilderDesired rate of new virtual users per second. This is similar to constantRate.usersPerSec phase settings but works closer to legacy benchmark drivers by fixing the concurrency.

compensation.metric

Configure a custom metric for the compensated results.

PropertyTypeDescription
<list of strings><list of strings>Allows categorizing request statistics into metrics based on the request path. The expressions are evaluated in the order as provided in the list. Use one of:
  • regexp -> replacement, e.g. ([^?])(?.)? -> $1 to drop the query part.
  • regexp (don’t do any replaces and use the full path), e.g. .*.jpg
  • -> name (metric applied if none of the previous expressions match).

compensation.targetRate

PropertyTypeDescription
basedoubleBase value used for first iteration.
incrementdoubleValue by which the base value is incremented for each (but the very first) iteration.

compression

PropertyTypeDescription
encodingStringEncoding used for Accept-Encoding/TE header. The only currently supported is gzip.
typeenumType of compression (resource vs. transfer based).
Options:
  • CONTENT_ENCODINGUse Accept-Encoding in request and expect Content-Encoding in response.
  • TRANSFER_ENCODINGUse TE in request and expect Transfer-Encoding in response.

CONNECT

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

DELETE

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

endpoint

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

GET

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

handler

Manages processing of HTTP responses.

PropertyTypeDescription
autoRangeCheckbooleanInject status handler that marks the request as invalid on status 4xx or 5xx. Default value depends on ergonomics.autoRangeCheck (see User Guide).
bodyProcessor.BuilderHandle HTTP response body.
followRedirectenumAutomatically fire requests when the server responds with redirection. Default value depends on ergonomics.followRedirect (see User Guide).
Options:
  • NEVERDo not insert any automatic redirection handling.
  • LOCATION_ONLYRedirect only upon status 3xx accompanied with a ’location’ header. Status, headers, body and completions handlers are suppressed in this case (only raw-bytes handlers are still running). This is the default option.
  • HTML_ONLYHandle only HTML response with META refresh header. Status, headers and body handlers are invoked both on the original response and on the response from subsequent requests. Completion handlers are suppressed on this request and invoked after the last response arrives (in case of multiple redirections).
  • ALWAYSImplement both status 3xx + location and HTML redirects.
headerHeaderHandler.BuilderHandle HTTP response headers.
onCompletionAction.BuilderAction executed when the HTTP response is fully received.
rawBytesRawBytesHandler.BuilderHandler processing HTTP response before parsing.
statusStatusHandler.BuilderHandle HTTP response status.
stopOnInvalidbooleanInject completion handler that will stop the session if the request has been marked as invalid. Default value depends on ergonomics.stopOnInvalid (see User Guide).

handler.header

Handle HTTP response headers.

PropertyTypeDescription
conditionalConditionalHeaderHandler.BuilderPasses the headers to nested handler if the condition holds. Note that the condition may be evaluated multiple times and therefore any nested handlers should not change the results of the condition.
countHeadersCountHeadersHandler.BuilderStores number of occurences of each header in custom statistics (these can be displayed in CLI using the stats -c command).
filterFilterHeaderHandler.BuilderCompares if the header name matches expression and invokes a processor with the value.
logInvalidLogInvalidHandler.HeaderHandlerBuilderLogs headers from requests marked as invalid.
recordHeaderTimeRecordHeaderTimeHandler.BuilderRecords alternative metric based on values from a header (e.g. when a proxy reports processing time).

handler.header.conditional

Passes the headers to nested handler if the condition holds. Note that the condition may be evaluated multiple times and therefore any nested handlers should not change the results of the condition.

PropertyTypeDescription
allConditionsBuilderCondition combining multiple other conditions with ‘AND’ logic.
boolConditionBuilderCondition comparing boolean variables.
handlerHeaderHandler.BuilderOne or more header handlers that should be invoked.
intConditionBuilderCondition comparing integer variables.
stringConditionBuilderCondition comparing string variables.

handler.header.conditional.allConditions

Test more conditions and combine the results using AND logic.

PropertyTypeDescription
<list of mappings><list of builders>List of conditions.

handler.header.conditional.allConditions.<list of mappings>

Selector for condition type.

PropertyTypeDescription
allConditionsBuilderCondition combining multiple other conditions with ‘AND’ logic.
boolConditionBuilderCondition comparing boolean variables.
intConditionBuilderCondition comparing integer variables.
stringConditionBuilderCondition comparing string variables.

handler.header.conditional.allConditions.<list of mappings>.allConditions

Test more conditions and combine the results using AND logic.

PropertyTypeDescription
<list of mappings><list of builders>List of conditions.

handler.header.conditional.allConditions.<list of mappings>.boolCondition

Tests session variable containing boolean value.

PropertyTypeDescription
fromVarStringVariable name.
valuebooleanExpected value.

handler.header.conditional.allConditions.<list of mappings>.intCondition

Condition comparing integer in session variable.

Inline definition
Parses condition in the form <variable> <operator> <value>
where operator is one of: ==, !=,
<> (the same as !=),
>=, >, <=, <.
PropertyTypeDescription
equalToBuilderCompared variable must be equal to this value.
fromVarObjectVariable name.
greaterOrEqualToBuilderCompared variable must be greater or equal to this value.
greaterThanBuilderCompared variable must be greater than this value.
isSetbooleanCheck if the value is set or unset. By default the variable must be set.
lessOrEqualToBuilderCompared variable must be lower or equal to this value.
lessThanBuilderCompared variable must be lower than this value.
notEqualToBuilderCompared variable must not be equal to this value.

handler.header.conditional.allConditions.<list of mappings>.stringCondition

Condition comparing string in session variable.

PropertyTypeDescription
caseSensitivebooleanTrue if the case must match, false if the check is case-insensitive.
endsWithCharSequenceSuffix for the string.
equalToCharSequenceLiteral value the string should match (the same as {@link #value}).
fromVarObjectVariable name.
isSetbooleanCheck if the value is set or unset. By default the variable must be set.
lengthintCheck the length of the string.
length (alternative)BuilderCheck the length of the string.
matchVarStringFetch the value from a variable.
negatebooleanInvert the logic of this condition. Defaults to false.
notEqualToCharSequenceValue that the string must not match.
startsWithCharSequencePrefix for the string.
valueCharSequenceLiteral value the string should match.

handler.header.conditional.boolCondition

Tests session variable containing boolean value.

PropertyTypeDescription
fromVarStringVariable name.
valuebooleanExpected value.

handler.header.conditional.handler

One or more header handlers that should be invoked.

PropertyTypeDescription
conditionalConditionalHeaderHandler.BuilderPasses the headers to nested handler if the condition holds. Note that the condition may be evaluated multiple times and therefore any nested handlers should not change the results of the condition.
countHeadersCountHeadersHandler.BuilderStores number of occurences of each header in custom statistics (these can be displayed in CLI using the stats -c command).
filterFilterHeaderHandler.BuilderCompares if the header name matches expression and invokes a processor with the value.
logInvalidLogInvalidHandler.HeaderHandlerBuilderLogs headers from requests marked as invalid.
recordHeaderTimeRecordHeaderTimeHandler.BuilderRecords alternative metric based on values from a header (e.g. when a proxy reports processing time).

handler.header.conditional.intCondition

Condition comparing integer in session variable.

Inline definition
Parses condition in the form <variable> <operator> <value>
where operator is one of: ==, !=,
<> (the same as !=),
>=, >, <=, <.
PropertyTypeDescription
equalToBuilderCompared variable must be equal to this value.
fromVarObjectVariable name.
greaterOrEqualToBuilderCompared variable must be greater or equal to this value.
greaterThanBuilderCompared variable must be greater than this value.
isSetbooleanCheck if the value is set or unset. By default the variable must be set.
lessOrEqualToBuilderCompared variable must be lower or equal to this value.
lessThanBuilderCompared variable must be lower than this value.
notEqualToBuilderCompared variable must not be equal to this value.

handler.header.conditional.intCondition.equalTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.intCondition.greaterOrEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.intCondition.greaterThan

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.intCondition.lessOrEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.intCondition.lessThan

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.intCondition.notEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition

Condition comparing string in session variable.

PropertyTypeDescription
caseSensitivebooleanTrue if the case must match, false if the check is case-insensitive.
endsWithCharSequenceSuffix for the string.
equalToCharSequenceLiteral value the string should match (the same as {@link #value}).
fromVarObjectVariable name.
isSetbooleanCheck if the value is set or unset. By default the variable must be set.
lengthintCheck the length of the string.
length (alternative)BuilderCheck the length of the string.
matchVarStringFetch the value from a variable.
negatebooleanInvert the logic of this condition. Defaults to false.
notEqualToCharSequenceValue that the string must not match.
startsWithCharSequencePrefix for the string.
valueCharSequenceLiteral value the string should match.

handler.header.conditional.stringCondition.length

PropertyTypeDescription
equalToBuilderCompared variable must be equal to this value.
greaterOrEqualToBuilderCompared variable must be greater or equal to this value.
greaterThanBuilderCompared variable must be greater than this value.
lessOrEqualToBuilderCompared variable must be lower or equal to this value.
lessThanBuilderCompared variable must be lower than this value.
notEqualToBuilderCompared variable must not be equal to this value.

handler.header.conditional.stringCondition.length.equalTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition.length.greaterOrEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition.length.greaterThan

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition.length.lessOrEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition.length.lessThan

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.conditional.stringCondition.length.notEqualTo

Inline definition
Uses the argument as a constant value.
PropertyTypeDescription
fromVarStringInput variable name.
valueintValue (integer).

handler.header.filter

Compares if the header name matches expression and invokes a processor with the value.

PropertyTypeDescription
headerBuilderCondition on the header name.
processorProcessor.BuilderAdd one or more processors.

handler.header.filter.header

Inline definition
Literal value the string should match.
PropertyTypeDescription
caseSensitivebooleanTrue if the case must match, false if the check is case-insensitive.
endsWithCharSequenceSuffix for the string.
equalToCharSequenceLiteral value the string should match (the same as {@link #value}).
lengthintCheck the length of the string.
length (alternative)BuilderCheck the length of the string.
matchVarStringFetch the value from a variable.
negatebooleanInvert the logic of this condition. Defaults to false.
notEqualToCharSequenceValue that the string must not match.
startsWithCharSequencePrefix for the string.
valueCharSequenceLiteral value the string should match.

handler.header.filter.header.length

PropertyTypeDescription
equalToBuilderCompared variable must be equal to this value.
greaterOrEqualToBuilderCompared variable must be greater or equal to this value.
greaterThanBuilderCompared variable must be greater than this value.
lessOrEqualToBuilderCompared variable must be lower or equal to this value.
lessThanBuilderCompared variable must be lower than this value.
notEqualToBuilderCompared variable must not be equal to this value.

handler.header.recordHeaderTime

Records alternative metric based on values from a header (e.g. when a proxy reports processing time).

PropertyTypeDescription
headerStringHeader carrying the time.
metricStringName of the created metric.
unitStringTime unit in the header; use either ms or ns.

handler.rawBytes

Handler processing HTTP response before parsing.

PropertyTypeDescription
transferSizeRecorderTransferSizeRecorder.BuilderAccumulates request and response sizes into custom metrics.

handler.rawBytes.transferSizeRecorder

Accumulates request and response sizes into custom metrics.

PropertyTypeDescription
keyStringName of the custom metric for collecting request/response bytes.

handler.status

Handle HTTP response status.

PropertyTypeDescription
actionActionStatusHandler.BuilderPerform certain actions when the status falls into a range.
counterStatusToCounterHandler.BuilderCounts how many times given status is received.
multiplexMultiplexStatusHandler.BuilderMultiplexes the status based on range into different status handlers.
rangeRangeStatusValidator.BuilderMarks requests that don’t fall into the desired range as invalid.
statsStatusToStatsHandler.BuilderRecords number of occurrences of each status counts into custom statistics (these can be displayed in CLI using stats -c).
storeStoreStatusHandler.BuilderStores the status into session variable.

handler.status.action

Perform certain actions when the status falls into a range.

PropertyTypeDescription
<any>BuilderPerform a sequence of actions if the range matches. Use range as the key and action in the mapping. Possible values of the status should be separated by commas (,). Ranges can be set using low-high (inclusive) (e.g. 200-299), or replacing lower digits with ‘x’ (e.g. 2xx).

handler.status.counter

Counts how many times given status is received.

PropertyTypeDescription
addintNumber to be added to the session variable.
expectStatusintExpected status (others are ignored). All status codes match by default.
initintInitial value for the session variable.
setintDo not accumulate (add), just set the variable to this value.
varStringVariable name.

handler.status.multiplex

Multiplexes the status based on range into different status handlers.

PropertyTypeDescription
<any>BuilderRun another handler if the range matches. Use range as the key and another status handler in the mapping. Possible values of the status should be separated by commas (,). Ranges can be set using low-high (inclusive) (e.g. 200-299), or replacing lower digits with ‘x’ (e.g. 2xx).

handler.status.multiplex.<any>

Run another handler if the range matches. Use range as the key and another status handler in the mapping. Possible values of the status should be separated by commas (,). Ranges can be set using low-high (inclusive) (e.g. 200-299), or replacing lower digits with ‘x’ (e.g. 2xx).

PropertyTypeDescription
actionActionStatusHandler.BuilderPerform certain actions when the status falls into a range.
counterStatusToCounterHandler.BuilderCounts how many times given status is received.
multiplexMultiplexStatusHandler.BuilderMultiplexes the status based on range into different status handlers.
rangeRangeStatusValidator.BuilderMarks requests that don’t fall into the desired range as invalid.
statsStatusToStatsHandler.BuilderRecords number of occurrences of each status counts into custom statistics (these can be displayed in CLI using stats -c).
storeStoreStatusHandler.BuilderStores the status into session variable.

handler.status.range

Marks requests that don’t fall into the desired range as invalid.

Inline definition
Single status code (204), masked code (2xx) or range (200-399).
PropertyTypeDescription
maxintHighest accepted status code.
minintLowest accepted status code.

handler.status.store

Stores the status into session variable.

Inline definition
Variable name.
PropertyTypeDescription
toVarObjectVariable name.

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

headers

PropertyTypeDescription
<any>StringUse header name (e.g. Content-Type) as key and value (possibly a pattern).
<any> (alternative)BuilderUse header name (e.g. Content-Type) as key and specify value in the mapping.

headers.<any>

Specifies value that should be sent in headers.

Inline definition
The value. This can be a
pattern.
PropertyTypeDescription
fromVarStringLoad header value from session variable.
patternStringLoad header value using a pattern.

metric

Allows categorizing request statistics into metrics based on the request path.

PropertyTypeDescription
<list of strings><list of strings>Allows categorizing request statistics into metrics based on the request path. The expressions are evaluated in the order as provided in the list. Use one of:
  • regexp -> replacement, e.g. ([^?])(?.)? -> $1 to drop the query part.
  • regexp (don’t do any replaces and use the full path), e.g. .*.jpg
  • -> name (metric applied if none of the previous expressions match).

OPTIONS

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

PATCH

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

path

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

POST

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

PUT

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.

sla

Defines a list of Service Level Agreements (SLAs) - conditions that must hold for benchmark to be deemed successful.

PropertyTypeDescription
<list of mappings><list of builders>One or more SLA configurations.

sla.<list of mappings>

Defines a Service Level Agreement (SLA) - conditions that must hold for benchmark to be deemed successful.

PropertyTypeDescription
blockedRatiodoubleMaximum allowed ratio of time spent waiting for usable connection to sum of response latencies and blocked time. Default is 0 - client must not be blocked. Set to 1 if the client can block without limits.
errorRatiodoubleMaximum allowed ratio of errors: connection failures or resets, timeouts and internal errors. Valid values are 0.0 - 1.0 (inclusive). Note: 4xx and 5xx statuses are NOT considered errors for this SLA parameter. Use invalidRatio for that.
invalidRatiodoubleMaximum allowed ratio of requests with responses marked as invalid. Valid values are 0.0 - 1.0 (inclusive). Note: With default settings 4xx and 5xx statuses are considered invalid. Check out ergonomics.autoRangeCheck or httpRequest.handler.autoRangeCheck to change this.
limitsBuilderPercentile limits.
meanResponseTimeStringMaximum allowed mean (average) response time. Use suffix ns, us, ms or s to specify units.
windowStringPeriod over which the stats should be collected. By default the SLA applies to stats from whole phase.

sla.<list of mappings>.limits

Percentile limits.

PropertyTypeDescription
<any>StringUse percentile (value between 0.0 and 1.0) as key and response time with unit (e.g. ms) in suffix as value.

TRACE

Generic builder for generating a string.

Inline definition
A pattern for string
interpolation.
PropertyTypeDescription
fromVarObjectLoad the string from session variable.
patternStringUse pattern replacing session variables.
valueStringString value used verbatim.