Documentation Grafana Cloud Observe and act Test and validate Synthetic Monitoring Create checks Check types

Check types

A Synthetic Monitoring check is a scheduled test of a target. The check is the configuration, not a single run: it defines what to test, what counts as success, how often to test, and which public or private probes run the test. The job name and target together uniquely identify a check. A check execution is one run of a check from one probe, so one check produces many executions over time.

Each check execution saves its results as Prometheus metrics and Loki logs, which you can use to configure Grafana alerts for custom notifications and incident management.

Synthetic Monitoring provides check types for endpoints, network paths, multi-step API workflows, scripts, and browser journeys.

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on Synthetic Monitoring Checks.

Try it

Choose a check type

The Synthetics app groups check types into four options on the Choose a check type page: API Endpoint, Multi Step, Scripted, and Browser.

Choose the simplest check type that verifies the outcome you care about. Use separate API Endpoint checks for independent targets. Use Multi Step, Scripted, or Browser when the requests or interactions form a single ordered journey.

Use the following table to choose a check type and find the option that creates it.

If more than one check type can verify what you care about, consider check frequency before you choose. Scripted and browser checks run at most once every 60 seconds, and traceroute checks at most once every 120 seconds, while the other check types run at most once every 10 seconds.

Browser test executions are billed separately from API test executions. The number of probes, execution duration, and check frequency also affect usage. For details, refer to Synthetic Monitoring pricing.

Monitor an endpoint that requires authentication

Which check type you need depends on how your endpoint authenticates requests:

• The endpoint uses basic authentication, bearer authentication, or a client certificate. Use an HTTP check. HTTP checks can use managed secrets for basic authentication passwords, bearer tokens, CA certificates, client certificates, and client keys. Refer to HTTP check authentication.

• The endpoint uses a sensitive credential in a custom request header. Use a k6 scripted check to read the credential from a managed secret and add it to the request. HTTP checks support custom request headers, but can’t read their values from managed secrets.

• Signing in is a request that returns a token or establishes a session cookie. Use a MultiHTTP check. MultiHTTP preserves cookies between requests. To reuse a token, capture it from the response with a variable and send it with later requests. Use a k6 scripted check if the flow needs logic that assertions and variables can’t express.

• Signing in means filling in a form in a web page. Use a k6 browser check. A browser check is the only check type that runs a real browser, so it’s the only one that can fill in a sign-in form, wait for the page that loads next, and continue as a signed-in user. For a worked example, refer to Create a k6 browser check.

HTTP, scripted, and browser checks can read supported values from secrets.

How checks run across probes

Every probe you select for a check runs that check independently at every interval. Probes don’t rotate between intervals, so if you select three probes and run a check every minute, the check executes three times per minute, once from each probe.

Each probe run counts as a separate execution for billing, and runs from different locations arrive at your target concurrently.

For details, refer to How probes run checks.

The check form

You configure every check type with the same five-step form. The form uses a consistent step order, but the available options vary by check type.

The first step is named Request for API Endpoint checks, Requests for Multi Step checks, and Script for Scripted and Browser checks. This step contains the fields for describing the request or writing the script. For API Endpoint checks, it also contains the Request type field, where you choose between HTTP, Ping, DNS, TCP, and Traceroute. Steps 2 through 5 have the same names for every check type.

The form indicates your current step. To move between steps, select a step or use the button labeled with the name of the next step.

Save stores the check and starts running it. It’s available from every step, so you don’t have to reach step 5 to save a check. The tabs next to the form provide additional actions:

• Test runs the check once without saving.
• Secrets selects the secrets the check can use. It appears for HTTP, Scripted, and Browser checks.
• Terraform displays the check as Terraform configuration.
• Docs links to reference documentation.

Check type identifiers

Each check type has an identifier that the REST API, Terraform, check metrics, and the Checks list use:

The Checks list displays the identifier as each check’s type. The REST API uses it as the key under settings; Terraform uses it as the block name inside settings in a grafana_synthetic_monitoring_check resource; and check metrics use it as the value of the check_name label.

Common options

Each check type has specific options. Enabled, Job name, Target, Probe locations, and Custom labels are the same on every check type. The frequency and timeout ranges in this table apply to DNS, HTTP, MultiHTTP, Ping, and TCP checks. For k6 and traceroute values, refer to k6 scripted checks, k6 browser checks, and traceroute checks.

Common check metrics

Checks collect the results of the execution and save them as Prometheus metrics.

Each check type produces specific Prometheus metrics with their results. To identify the check type in a query, use the check_name label on sm_check_info, whose values are the check type identifiers. The following is a list of metrics common to all check types.

For the list of additional metrics, refer to the metrics documentation for each check type: DNS metrics, HTTP metrics, k6 browser metrics, k6 scripted metrics, MultiHTTP metrics, Ping metrics, TCP metrics, and Traceroute metrics.

Metric labels

In Prometheus, labels add additional context to the metrics, and can be used for querying and visualizations.

All check metrics include the system labels config_version, instance, job, and probe. Some check options and metric types add labels to provide additional information.

The sm_check_info metric also includes static metadata labels such as check_name and geohash. For the complete reference of the labels that Synthetic Monitoring applies to metrics and logs, refer to System labels.

Custom label names can’t collide with the reserved system label names: the API rejects checks that use a reserved name as a custom label. For details, refer to System labels.

Note that each unique metric name and label set creates a new time series.