Required: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples.
metric
string
Required: name of the metric to query, with optional labels selector. Example: `http_reqs{expected_response=“true”}
step
int
Optional: The step size in seconds for the query range.
start
iso8601
Optional: The start timestamp for the query range. Default is test run start. Example: 2022-11-23T10:03:00Z
end
iso8601
Optional: The end timestamp for the query range. Default is test run end. Example: 2022-11-23T10:13:00Z
Example request:
http
GET https://api.k6.io/cloud/v5/test_runs/152779/query_range_k6(query='increase by (name,status)',metric='http_reqs{status!="0"}',step=5)
Accept:application/jsonAuthorization:Token 56c166885f9a7fc1e588a1b3cb66f6dd
GET https://api.k6.io/cloud/v5/test_runs/152779/query_range_k6(query='increase by (name,status)',metric='http_reqs{method="GET",status="2\d\d"}',step=5,start=2022-11-23T10:03:00Z,end=2022-11-23T10:13:00Z)
Accept:application/jsonAuthorization:Token 56c166885f9a7fc1e588a1b3cb66f6dd
Query aggregate values
GET /test_runs/:testRunId/query_aggregate_k6(:parameters)
Aggregate query returns a single sample value for a given metric over the duration of the test run.
Parameters are a comma-separated list in the format of key=value. String values should be surrounded by single quotes '.
Required: query expression for selecting metrics. Possible values depend on the metric type. See below for detailed list and examples.
metric
string
Required: name of the metric to query, with optional labels selector. Example: `http_reqs{expected_response=“true”}
start
iso8601
The start timestamp for the query range. Default is test run start. Example: 2022-01-02T10:03:00Z
end
iso8601
The end timestamp for the query range. Default is test run end. Example: 2022-01-02T10:13:00Z
Example request:
http
GET https://api.k6.io/cloud/v5/test_runs/152779/query_aggregate_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration')
Accept:application/jsonAuthorization:Token 56c166885f9a7fc1e588a1b3cb66f6dd
The metric parameter can be used to specify the metric name and optional label filter.
The syntax is similar to that of Prometheus selectors: metric name, e.g. http_reqs, followed by optional label filters in curly braces,
e.g. {status="200"}.
The following operators are supported for label matching:
=: Equal to the provided string.
!=: Not equal to the provided string.
=~: Regex-match the provided string.
!~: Do not regex-match the provided string.
Examples:
http_req_duration
http_req_duration{status="200"}
http_req_duration{status~="(2|3)\d\d"}
http_req_duration{status!="0"}
http_req_duration{status!="0",name="login page"}
Specifying query expression
The query parameter can be used to specify the function applied to the metric to produce values.
Basic methods
A method is a basic function that gives a numerical value when applied to some time span of a
metric.
For range queries (like the ones that produce graphs over time) the timespans are windows between
each returned datapoint.
For aggregate queries (like getting total number of requests in the test run) the timespan is the
whole test run.
k6 has 4 metric types: Counter, Gauge, Rate and Trend.
Each of these offer a distinct set of methods for operating that data type.
Counter methods
Method
Description
PromQL equivalent
increase
Total increase of counter’s value in the time span. For a metric like http_reqs this will be the number of requests.
increase(metric_name[$__interval])
rate
Average increase per second. Equals to increase divided by time span size in seconds.
rate(metric_name[$__interval])
value
Growing counter value.
metric_name
cumrate
Cumulative rate from test run start. Equals to value divided by time elapsed since test run start.
max_rate(<interval>)
Get rate for each <interval> seconds within time span and return the max value. Used e.g. for “peak RPS” value in test run stats. <interval> must be an integer.
Using a method as-is to query a metric produces a single time series, aggregating all values.
To preserve some labels and get multiple time series, use the following syntax:
<method> by (<label list>)
Examples:
# 95th-percentiles or "http_req_duration" metric (Trend), separated by URL ("name" label) and HTTP status ("status" label)
histogram_quantile(0.95) by (name, status)
# Peak CPU usage (Gauge) for each load generator instance
max by (instance_id)
Aggregating over labels dimension
You can further aggregate time series produced with queries using by syntax.
Use aggregators to aggregate values for each time bucket across labels dimensions.
# Active VUs count on "vus" metric
sum(last by (instance_id))
# Average request rate on "http_reqs" metric across URLs, separated by HTTP method
avg(rate by (name, method)) by (method)