> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Synthetic monitoring

> Create active HTTP, browser, network, and heartbeat checks, run them from embedded or private locations, and publish verified revisions.

Synthetic monitoring tests a service from the outside before a customer reports a failure. Open
**Synthetics** to create checks, publish schedules, inspect execution evidence, and manage private
Probe locations.

## What you can monitor

| Check type      | Use it for                                                                   |
| --------------- | ---------------------------------------------------------------------------- |
| **HTTP / API**  | Validate a URL, method, headers, body, response status, content, and timing. |
| **Browser**     | Run a browser journey and assert page or step outcomes.                      |
| **TCP**         | Confirm that a host and port accept a connection.                            |
| **DNS**         | Resolve records and validate the returned answer.                            |
| **ICMP / Ping** | Measure basic host reachability and latency.                                 |
| **TLS**         | Validate a TLS handshake, certificate identity, and expiry.                  |
| **gRPC**        | Call a gRPC endpoint and validate the response.                              |
| **Heartbeat**   | Expect an external job or service to report before its deadline.             |

## Create and publish a check

<Steps>
  <Step title="Create a draft">
    Open **Synthetics → Checks**, select **Create check**, then choose a type. Configure the target,
    timeout, assertions, schedule, and one or more locations. A new check starts as a draft.
  </Step>

  <Step title="Test the revision">
    Select **Test revision**. MoleSignal runs the draft without activating its schedule. Review the
    resolved target, attempts, timings, assertion evidence, and errors.
  </Step>

  <Step title="Publish the revision">
    A successful test enables **Publish revision**. Publishing makes the revision active and
    calculates its first scheduled run.
  </Step>

  <Step title="Operate the monitor">
    Use **Run now** for an on-demand execution. Editing creates another draft revision, so the
    published configuration continues running until the replacement is tested and published.
    Pause, resume, or archive the check without deleting its result history.
  </Step>
</Steps>

<Note>
  The draft gate prevents an untested target or assertion from silently replacing a working
  production schedule.
</Note>

## Schedule and retries

Use an interval or a cron expression with an explicit timezone. Most active checks accept intervals
from 10 seconds to one day; browser checks start at 60 seconds. Set the timeout between 100
milliseconds and five minutes, and keep it shorter than the interval. A run can retry up to two
times before MoleSignal records its final outcome.

Heartbeat checks use a reporting deadline rather than an outbound schedule. Send the heartbeat from
the workload that owns the job, then use the result history to distinguish a late report from a
failed active probe.

## Assertions and health

Assertions inspect protocol-specific fields such as response status, body, headers, DNS answers,
certificate properties, or browser outcomes. A failed **Warning** assertion produces a degraded
result; a failed **Critical** assertion produces a failing result.

The monitor health state is calculated from consecutive successes and failures across its selected
locations. Configure the failure threshold, recovery threshold, and location policy to avoid
flapping or declaring a global outage from one isolated network.

## Locations and Probe Agents

MoleSignal supports two location models:

| Location           | Behavior                                                                                                                                                       |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Embedded Local** | A Standalone deployment starts an in-process Probe runner automatically. It is useful for local evaluation and checks that should originate beside MoleSignal. |
| **Agent Pool**     | One or more external <code>probe-agent</code> processes execute checks from a private network, region, or edge location.                                       |

Create an Agent Pool location under **Synthetics → Locations**, generate a one-time register
token, and register the Agent:

```bash theme={null}
probe-agent register \
  --endpoint https://molesignal.example.com:5084 \
  --token ONE_TIME_TOKEN \
  --ca-certificate-base64 BASE64_CA
```

Then start its control stream:

```bash theme={null}
probe-agent run
```

Registration uses server-authenticated TLS. The Agent stores a private identity under
<code>--state-dir</code> and uses mTLS for the control stream on port 5085. The default state
directory is <code>/var/lib/molesignal-probe</code>.

Configure the server endpoints in <code>conf/config.toml</code>:

The Probe control plane starts automatically on **Standalone** and **Alert Manager** nodes; it has
no separate enable switch.

```toml theme={null}
[probe]
bind = "0.0.0.0"
register_port = 5084
control_port = 5085
register_endpoint = "https://molesignal.example.com:5084"
control_endpoint = "https://molesignal.example.com:5085"
server_names = ["molesignal.example.com"]
```

<Warning>
  An egress policy applies before every network request. Loopback, link-local, or private addresses
  are rejected unless the selected location policy explicitly allows them. This protects the
  MoleSignal host and private network from server-side request forgery.
</Warning>

## Variables, secrets, and evidence

Use variables for reusable non-sensitive values and encrypted secrets for credentials. Secret
values are write-only and never returned by the API. Result detail records bounded request and
response evidence, timings, attempt metadata, the selected location, and the active revision
without exposing stored secrets.

## Publish failures to a status page

A status-page automation rule can use **Synthetic monitor** as its source. Select the monitor,
match its transition and severity, map the impact to components, and choose either manual approval
or automatic publishing. See [Status pages](/en-US/status-pages#publication-automation).

## Permissions

| Permission                               | Capability                                                                    |
| ---------------------------------------- | ----------------------------------------------------------------------------- |
| <code>synthetics.read</code>             | Read checks, revisions, schedules, runs, results, locations, and Agent state. |
| <code>synthetics.manage</code>           | Create, test, publish, pause, resume, run, and archive checks.                |
| <code>synthetics.locations.manage</code> | Manage locations, Agent pools, register tokens, and egress policies.          |
| <code>synthetics.secrets.manage</code>   | Create, rotate, and remove encrypted synthetic-monitoring secrets.            |

<CardGroup cols={2}>
  <Card title="Status pages" icon="signal" href="/en-US/status-pages">
    Turn monitor transitions into reviewed or automatic customer communication.
  </Card>

  <Card title="Alerting" icon="bell" href="/en-US/alerting">
    Route operational incidents to responders before publishing customer updates.
  </Card>
</CardGroup>