Menu
Grafana Cloud

k6 browser check

Note

k6 browser checks are currently in private preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

Contact support to have the feature enabled.

k6 browser checks run a k6 script using the browser module to control a headless browser. Browser checks monitor web performance and can be used to continuously monitor critical user journeys and workflows.

With k6 browser checks, you can:

  • Perform interactions on a web page like navigation, tap/click, filling forms, and scrolling.
  • Leverage a Playwright-compatible API for authoring tests.
  • Simultaneously make requests at the protocol-level as well as in the browser, to simulate user behavior and rich interactive scenarios.
  • Set the window size to test mobile, tablet, and desktop views.

How it works

A k6 check runs one iteration of a k6 test at short, frequent intervals to proactively monitor applications and services.

Synthetic Monitoring results are stored as Prometheus metrics and Loki logs, which allow you to set up Grafana alerts for custom notifications and incident management.

The k6 scripts in Synthetic Monitoring are 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.

Create a k6 browser check

You can write and execute a k6 script from the code editor in the Synthetics UI.

  1. On the main menu, select Testing & synthetics and then Synthetics.
  2. Click Create new check or Add new check.
  3. Choose k6 browser as your check type.
  4. Set the value for the required options.
  5. Edit or copy your k6 script under Script.
  6. Schedule or run the check.
    1. Click Save to schedule the check.
    2. 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. Alternatively, you can use the k6 DevTools recorder to generate a script for you. After completing the k6 script, create a new browser 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 browser tests, refer to the Create a k6 browser check tutorial.

Options

The list of common options to all check types:

OptionDescription
EnabledWhether the check is enabled or not.
Job nameRefer to the check name. Check metrics include a job label with the value of this option.
TargetTarget of the check request. Check metrics include an instance label with the value of this option.
Probe locationsThe locations where the check should run from. Check metrics include a probe label with the value of the probe location running the check.
FrequencyThe 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.
TimeoutMaximum 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:

OptionDescription
ScriptThe k6 script to execute periodically. For further details, refer to k6 compatibility.

Required k6 imports and options

In order to run a browser check, the script must:

  • Import the browser module
  • Include the browser type “chromium” in the k6 options block.
JavaScript
import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

Supported k6 Options

k6 options can be used to configure a wide range of features when running the k6 script. In Synthetic Monitoring, k6 options can only be set in the script options object:

JavaScript
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 OptionDescription
batchMax number of simultaneous connections of a http.batch() call
batch-per-hostMax number of simultaneous connections of a http.batch() call for a host
discardResponseBodiesSpecify whether response bodies should be discarded
httpDebuglog all HTTP requests and responses
insecureSkipTLSVerifyA boolean specifying whether k6 should ignore TLS verifications for connections established from code
maxRedirectsThe maximum number of HTTP redirects that k6 will follow
noConnectionReuseA boolean specifying whether k6 should disable keep-alive connections
setupTimeoutSpecify how long the setup() function is allow to run before it’s terminated
systemTagsSpecify which System Tags will be in the collected metrics
tagsSpecify tags that should be set test-wide across all metrics
teardownTimeoutSpecify how long the teardown() function is allowed to run before it’s terminated
throwA boolean specifying whether to throw errors on failed HTTP requests
tlsAuthA list of TLS client certificate configuration objects
tlsCipherSuitesA list of cipher suites allowed to be used by in SSL/TLS interactions with a server
tlsVersionString or object representing the only SSL/TLS version allowed
userAgentA 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:

MetricDescription
probe_all_duration_secondsReturns how long the probe took to complete in seconds (histogram).
probe_duration_secondsReturns how long the probe took to complete in seconds.
probe_all_successDisplays whether or not the probe was a success (summary).
probe_successDisplays whether or not the probe was a success.
sm_check_infoProvides information about a single check configuration.

k6 metrics

Browser 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. In addition, browser checks collect Web Vitals metrics.
  • Custom metrics: These are metrics that you can create in your test script to measure anything 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 for browser checks are transformed in Synthetic Monitoring as follows:

MetricDescription
probe_browser_data_receivedThe total data received for all requests made in executing the script. It corresponds to the data_received metric.
probe_browser_data_sentThe total data sent for all requests made in executing the script. It corresponds to the data_sent metric.
probe_browser_http_req_durationDuration 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_browser_http_req_failedThe number of failed HTTP requests while executing the script.
probe_browser_web_vital_clsMeasures the visual stability on a webpage by quantifying the amount of unexpected layout shift of visible page content. Refer to Cumulative Layout Shift for more information.
probe_browser_web_vital_fcpMeasures the time it takes for the browser to render the first DOM element on the page, whether that’s a text, image or header. Refer to First Contentful Paint for more information.
probe_browser_web_vital_fidMeasures the responsiveness of a web page by quantifying the delay between a user’s first interaction, such as clicking a button, and the browser’s response. Refer to First Input Delay for more information.
probe_browser_web_vital_inpAn experimental metric that measures a page’s responsiveness. Refer to Interaction to Next Paint for more information.
probe_browser_web_vital_lcpMeasures the time it takes for the largest content element on a page to become visible. Refer to Largest Contentful Paint for more information.
probe_browser_web_vital_ttfbMeasures the time it takes between the browser request and the start of the response from a server. Refer to Time to First Byte for more information.
probe_checks_totalThe number of passing/failing assertions made (calls to check()). The result label has a value of pass or fail.
probe_iteration_duration_secondsReturns 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.

k6 browser check dashboard

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 check runs only one iteration of the k6 test. Options such as vus, duration, stages, and iterations are omitted.

  • Timeout

    k6 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, and grpc.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 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.

Public preview limitations

  • Each stack is limited to 10 browser checks.
  • Browser checks on private probes aren’t supported.
  • Configuring Browser checks with Terraform isn’t supported.
  • Browser checks can run for a maximum of 1 minute.