k6 scripted check
Note
k6 scripted checks is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
k6 scripted checks can execute k6 tests in Synthetic Monitoring. Use k6 scripted checks to monitor transactions and user flows by implementing workflows, custom logic, and validations in JavaScript.
With k6 scripted checks, you can:
- Define custom user behavior and complex request logic.
- Leverage the flexibility of a scripting language.
- Test HTTP/S and WebSocket services.
- Utilize the k6 API and other JavaScript libraries.
- Enable OpenTelemetry traces for server-side correlation.
- Reuse the same k6 script for distinct testing goals.
How it works
A k6 scripted check runs a k6 test (limited to one iteration) at short, frequent intervals to proactively monitor applications and services, 24/7.
Synthetic Monitoring results are stored as Prometheus metrics and Loki logs, allowing the setup of Grafana alerts for custom notifications and incident management.
The k6 script for Synthetic Monitoring is broadly compatible with other k6 products, like the k6 CLI and Grafana Cloud Performance Testing. This allows you to reuse the same k6 script for various use cases, enhancing testing productivity and coverage.
Get started
You can write and execute a k6 script from the code editor in the Synthetics UI.
- On the left-side menu, select Testing & synthetics and then Synthetics.
- Click Create new check or Add new check.
- Choose k6 scripted as your check type.
- Set the value for the required options.
- Edit or copy your k6 script under Script.
- Schedule or run the check.
- Click Save to schedule the check.
- Click Test to run the k6 script.
For development and debugging, you can write and execute the k6 script from your local machine using the k6 CLI and your IDE. After completing the k6 script, create a new scripted check or update the script of an existing one.
The Synthetics script editor includes a few scripts with basic examples. To get started implementing your first k6 scripts, refer to:
Options
The list of common options to all check types:
Option | Description |
---|---|
Enabled | Whether the check is enabled or not. |
Job name | Refer to the check name. Check metrics include a job label with the value of this option. |
Target | Checks must include the Job name and Target options to generate its unique identifier. Check metrics include an instance label with the value of this option. |
Probe locations | The locations where the check should run from. Check metrics include a probe label with the value of the probe location running the check. |
Frequency | The frequency the check should run in seconds. The value can range from 60 to 3600 seconds. Only the sm_check_info metric includes the frequency label. |
Timeout | Maximum execution time for the check. The value can range from 1 to 60 seconds. |
Custom labels | (Optional) Custom labels applied to check metrics. Refer to Custom labels for querying instructions. |
Additionally, k6 scripted checks have the following options:
Option | Description |
---|---|
Script | The k6 script to execute periodically. For further details, refer to k6 compatibility. |
Supported k6 Options
k6 options allow configuring a wide range of features when running the k6 script. In Synthetic Monitoring, k6 options can only be set in the script options
object:
export const options = {
tags: { foo: 'bar' },
userAgent: 'MyK6UserAgentString/1.0',
};
Several k6 options don’t apply in the context of Synthetic Monitoring. Here is the list of supported options:
k6 Option | Description |
---|---|
batch | Max number of simultaneous connections of a http.batch() call |
batch-per-host | Max number of simultaneous connections of a http.batch() call for a host |
discardResponseBodies | Specify whether response bodies should be discarded |
httpDebug | log all HTTP requests and responses |
insecureSkipTLSVerify | A boolean specifying whether k6 should ignore TLS verifications for connections established from code |
maxRedirects | The maximum number of HTTP redirects that k6 will follow |
noConnectionReuse | A boolean specifying whether k6 should disable keep-alive connections |
setupTimeout | Specify how long the setup() function is allow to run before it’s terminated |
systemTags | Specify which System Tags will be in the collected metrics |
tags | Specify tags that should be set test-wide across all metrics |
teardownTimeout | Specify how long the teardown() function is allowed to run before it’s terminated |
throw | A boolean specifying whether to throw errors on failed HTTP requests |
tlsAuth | A list of TLS client certificate configuration objects |
tlsCipherSuites | A list of cipher suites allowed to be used by in SSL/TLS interactions with a server |
tlsVersion | String or object representing the only SSL/TLS version allowed |
userAgent | A string specifying the User-Agent header when sending HTTP requests |
Metrics
Synthetic checks store their results as Prometheus metrics, including the list of common metrics to all check types:
Metric | Description |
---|---|
probe_all_duration_seconds | Returns how long the probe took to complete in seconds (histogram). |
probe_duration_seconds | Returns how long the probe took to complete in seconds. |
probe_all_success | Displays whether or not the probe was a success (summary). |
probe_success | Displays whether or not the probe was a success. |
sm_check_info | Provides information about a single check configuration. |
k6 metrics
Scripted checks also collect the metrics produced by k6 and store them as Prometheus metrics.
k6 has two types of metrics:
- Built-in metrics: These are metrics collected by every k6 test, such as data received and total number of requests.
- Custom metrics: These are metrics that you can create in your test script to measure anything that’s specific to your system or business logic. In Prometheus, they’re renamed to
probe_K6_METRIC_NAME
and mapped to Prometheus gauges.
k6 built-in metrics are transformed in Synthetic Monitoring as follows:
Metric | Description |
---|---|
probe_checks_total | The number of passing/failing assertions made (calls to check() ). The result label has a value of pass or fail . |
probe_data_received_bytes | The total data received for all requests made in executing the script. It corresponds to the data_received metric. |
probe_data_sent_bytes | The total data sent for all requests made in executing the script. It corresponds to the data_sent metric. |
probe_http_duration_seconds | Duration of HTTP request by phase, in seconds. This is the combined total of the http_req_blocked , http_req_connecting , http_req_receiving , http_req_sending , http_req_tls_handshaking , and http_req_waiting k6 HTTP metrics. |
probe_http_error_code | The k6 error code for the HTTP request. |
probe_http_got_expected_response | The expected_reponse tag set on HTTP requests by k6. By default, response statuses between 200 and 399 are true. For more details, refer to k6 HTTP Request Tags. |
probe_http_info | This metric includes additional labels associated with an HTTP request such as HTTP version, TLS version, and error message on failed requests. It always returns a value of 1. |
probe_http_requests_failed_total | The number of failed HTTP requests while executing the script. |
probe_http_requests_total | The number of HTTP requests initiated while executing the script. |
probe_http_ssl | Indicates if TLS was used in the request. |
probe_http_status_code | Response HTTP status code. |
probe_http_total_duration_seconds | Duration of HTTP request (in seconds). It corresponds to the http_req_duration metric. |
probe_http_version | Returns the HTTP version of the response. |
probe_iteration_duration_seconds | Returns the amount of time it took the script to execute, in seconds. It corresponds to the iteration_duration metric. |
Visualization
You can query all the produced check metrics with Grafana Explore
, where you can create custom panels and add them to your dashboards.
Additionally, each check includes a dashboard displaying the results of the most relevant metrics. To learn more about the various visualization options, refer to Analyze results.
Compatibility
There are some limitations when running k6 scripts in Grafana Cloud Synthetic Monitoring, compared to running them locally or using Grafana Cloud k6:
Workload options
A k6 scripted check runs only one iteration of the k6 test. Options such as
vus
,duration
,stages
, anditerations
are omitted.Timeout
k6 scripted checks have a maximum execution time, configured by the
Timeout
option in the UI.k6 CLI
The k6 CLI can’t run or upload k6 scripts in Grafana Cloud Synthetic Monitoring.
Load files
Probes can’t load local files for security reasons. k6 APIs like
open
,fs
, andgrpc.load
(non-reflection) are unsupported.Importing a local module or local library isn’t possible from the UI. Alternatively, you can use a bundler to build the k6 script with its dependencies locally and copy it into the script option.
Other k6 APIs
Thresholds and the browser module aren’t supported.
Labels
Custom labels defined in the UI aren’t included in k6 metrics. The non-k6 metrics don’t include the labels defined in the k6
tags
option.
Was this page helpful?
Related documentation
Related resources from Grafana Labs
![Getting started with the Grafana LGTM Stack](/static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=200 200w, /static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=400 400w)
![Intro to Kubernetes monitoring in Grafana Cloud](/media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=200 200w, /media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=400 400w)
![Building advanced Grafana dashboards](/media/webinar/AMER_buildadv_notxt.png?w=200 200w, /media/webinar/AMER_buildadv_notxt.png?w=400 400w)