# Synthetics

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 BYOC 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](https://docs.groundcover.com/use-groundcover/monitors "mention")). Using monitors you can get alerted on failed synthetic tests, see: [workflow-integrations](https://docs.groundcover.com/integrations/workflow-integrations "mention") . 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` .

{% hint style="info" %}
Only Editors can create/edit/delete synthetic tests, see [#default-policies](https://docs.groundcover.com/use-groundcover/role-based-access-control-rbac#default-policies "mention")
{% endhint %}

#### 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.

<table data-header-hidden><thead><tr><th width="161.6328125"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>statusCode</td><td>Checks the HTTP response code (e.g., <code>200</code>, <code>404</code>, <code>500</code>).</td></tr><tr><td>responseHeader</td><td>Checks for the presence or value of a specific response header (e.g., <code>Content-Type</code>).</td></tr><tr><td>jsonBody</td><td>Inspects specific keys or values within a JSON response payload.</td></tr><tr><td>body</td><td>Checks the raw text body of the response.</td></tr><tr><td>responseTime</td><td>Checks the response time of the response</td></tr><tr><td>jsonBody</td><td>Inspects specific keys or values within a JSON response payload.</td></tr></tbody></table>

**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](https://docs.groundcover.com/use-groundcover/monitors "mention") .

* **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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/capabilities/synthetics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.