Synthetics (Beta)

Synthetics allow you to proactively monitor the health, availability, and performance of your endpoints. By simulating requests from your infrastructure, you can verify that your critical services are reachable and returning correct data, even when no real user traffic is active.

Overview

groundcover Synthetics execute checks from your installed groundcover backend, working on inCloud deployments only.

• Source: Checks run from within your backend, when having multiple groundcover backends you can select the specific backend to use. We will support region selection for running tests from specific locations.

• Supported Protocols: Currently, Synthetics supports HTTP/HTTPS tests. Support for additional protocols, including gRPC, ICMP (Ping), DNS, and dedicated SSL monitors are coming soon.

• Alerting: Creating a Synthetic test automatically creates a corresponding Monitor (See: Monitors). Using monitors you can get alerted on failed synthetic tests, see: Notification Channels . The monitor is uneditable.

• Trace Integration: We generate traces for all synthetic tests, which you can see as first-class citizens in groundcover platform. You can query these traces by using source:synthetics in traces page.

Creating a Synthetic Test

Navigate to Monitors > Synthetics and click + Create Synthetic Test .

Only Editors can create/edit/delete synthetic tests, see Default Policies

Request Configuration

Define the endpoint and parameters for the test.

• Synthetic Test Name: A descriptive name for the test.

• Target: Select the method (GET, POST, etc.) and URL. Include HTTP scheme as well, for example: https://api.groundcover.com/api/backends/list

  • Tip: Use Import from cURL to paste a command and auto-fill these fields.

• HTTP Settings

  • Follow redirects: Should the test follow 3xx responses, when disabled the test will return the 3xx response as the result set for assertions.

  • Allow insecure: Disables SSL/TLS certificate verification. Use this only for internal testing or self-signed certificates. Not recommended for production endpoints as it exposes you to Man-in-the-Middle attacks.

  • HTTP Version: Select the protocol version: one of HTTP/1.0, HTTP/1.1 or HTTP/2.0 . Default is HTTP/1.1

• Timing

  • Interval: Frequency of the check (e.g., every 60s).

  • Timeout: Max duration to wait before marking the test as failed. Timeout must be less than interval.

• Payload: Select the body type if your request requires data (e.g., POST/PUT).

  • Options: None, JSON, Text, Raw.

• Headers & Auth:

  • Authentication (Bearer tokens, API keys) will be released soon.

  • Headers: You can add custom headers passing key and values.

Assertions (Validation Logic)

Assertions are the rules that determine if a test passed or failed. You can add multiple assertions to a single test. If any assertion fails, the entire check is marked as failed.

Available Assertion Fields

The "Field" determines which part of the response groundcover inspects.

Field	Description
statusCode	Checks the HTTP response code (e.g., 200, 404, 500).
responseHeader	Checks for the presence or value of a specific response header (e.g., Content-Type).
jsonBody	Inspects specific keys or values within a JSON response payload.
body	Checks the raw text body of the response.
responseTime	Checks the response time of the response
jsonBody	Inspects specific keys or values within a JSON response payload.

Assertion Operators

The "Operator" defines the logic applied to the Field.

Operator	Function	Example Use Case
is equal to	Exact match. Case-sensitive.	statusCode is equal to 200
is not equal to	Ensures a value does not appear.	statusCode is not equal to 500
contains	Checks if a substring exists within the target.	body contains "error"
starts with	Verifies the beginning of a string.	"status"
ends with	Verifies the end of a string.	"success"
matches regex	Validates against a Regular Expression.	jsonBody matches regex user_id: \d+
exists	Checks that a field or header is present, regardless of value.	set-cookie exists in response headers
does not exist	Checks that a field is absent.	jsonBody (error_message) does not exist
is one of	Checks against a list of acceptable values.	statusCode is one of 200, 201, 202

Custom Labels

Add custom labels, these labels will exist on traces generated by checks. You can use these labels to filter traces.

Auto-Generated Monitors

When you create a Synthetic Test, groundcover eliminates the need to manually configure separate alert rules. A Monitor is automatically generated and permanently bound to your test. See: Monitors .

• Managed Logic: The monitor's threshold and conditions are derived directly from your Synthetic Test's assertions. If the test fails (e.g., status code != 200), the Monitor automatically enters a "Failing" state.

• Lifecycle: This monitor handles the lifecycle of the alert, transitioning between Pending, Firing (when the test fails), and Resolved (when the test passes).

• Zero Maintenance: You do not need to edit this monitor's query. Any changes you make to the Synthetic Test (such as changing the target URL or assertions) are automatically synced to the Monitor.

Note: To prevent configuration drift, these auto-generated monitors are read-only. You cannot edit their query logic directly; you simply edit the Synthetic Test itself.