# Monitor HTTP endpoints with Uptrace

> Add synthetic HTTP endpoint monitoring to Uptrace using the OpenTelemetry httpcheckreceiver — uptime checks, response validation, and TLS certificate expiry tracking.

Synthetic monitoring periodically checks your HTTP endpoints and reports the results as OpenTelemetry metrics. This guide shows you how to configure the OpenTelemetry Collector to check your endpoints and view the results in Uptrace.

**Prerequisite:** OpenTelemetry Collector already running and sending data to Uptrace. If not, start with [Getting started](/get).

## Basic endpoint check

Add the `httpcheck` receiver to your Collector config and include it in the metrics pipeline:

```yaml
receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
    collection_interval: 60s

processors:
  batch:

exporters:
  otlp:
    endpoint: api.uptrace.dev:4317
    headers: { 'uptrace-dsn': '<your-dsn>' }

service:
  pipelines:
    metrics:
      receivers: [httpcheck]
      processors: [batch]
      exporters: [otlp]
```

If your Collector already has a metrics pipeline, add `httpcheck` to the existing `receivers` list instead of replacing it.

Restart the Collector. After one collection interval you will see `httpcheck_*` metrics in Uptrace — open the **Metrics** section and search for `httpcheck`.

## Monitor multiple endpoints

Add as many targets as you need. Each target produces metrics tagged with its `http_url`:

```yaml
receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
      - endpoint: 'https://app.example.com'
        method: GET
      - endpoint: 'https://staging.example.com/health'
        method: GET
    collection_interval: 60s
```

## Validate the response body

Use `validations` to catch cases where the server returns 200 but the response content signals a problem:

```yaml
receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
        validations:
          - contains: '"status":"ok"'
          - not_contains: '"degraded"'
      - endpoint: 'https://api.example.com/v2/status'
        method: GET
        validations:
          - json_path: 'health'
            equals: 'true'
    collection_interval: 60s
    metrics:
      httpcheck.validation.failed:
        enabled: true
```

When a validation fails, `httpcheck_validation_failed` is incremented. `httpcheck_status` still reflects only the HTTP status class, so a `200` response with invalid content can keep the `2xx` status series at `1`. Alert on `httpcheck_validation_failed` when response content matters. See the [reference guide](/guides/opentelemetry-httpcheck#enabling-optional-metrics) for other optional validation metrics.

## Track TLS certificate expiry

Enable the `httpcheck_tls_cert_remaining` metric to monitor how many seconds are left before a certificate expires:

```yaml
receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com'
        method: GET
    collection_interval: 3600s   # once per hour is enough for cert checks
    metrics:
      httpcheck.tls.cert_remaining:
        enabled: true
```

The metric includes `http_tls_issuer`, `http_tls_cn`, and `http_tls_san` attributes so you can identify which certificate is expiring. A negative value means the certificate has already expired.

## Verify in Uptrace

Open the **Metrics** section and search for `httpcheck`. You should see:

- `httpcheck_status` — one series per `http_status_class`; filter to `http_status_class="2xx"` when checking whether a URL is up
- `httpcheck_duration` — round-trip time in milliseconds per endpoint
- `httpcheck_error` — populated only when a check throws a network-level error
- `httpcheck_validation_failed` — incremented when enabled response validations fail

If no metrics appear after two collection intervals, confirm the Collector host can reach your endpoints (`curl https://api.example.com/health` from the Collector machine) and check the Collector logs for errors from the `httpcheck` receiver.

## Build a dashboard

Once metrics are flowing, open [Dashboards](/features/dashboards) and create panels from the `httpcheck_*` namespace:

- **Uptime** — `httpcheck_status` filtered to `http_status_class="2xx"` and grouped by `http_url`, as a status timeline or percentage over the selected range
- **Response time** — `httpcheck_duration` per URL as a line chart; add a threshold line for your SLO
- **Errors** — `httpcheck_error` grouped by `http_url` and `error_message` to see failure reasons at a glance
- **Validation failures** — `httpcheck_validation_failed` grouped by `http_url` and `validation_type` to catch invalid response content
- **Certificate expiry** — `httpcheck_tls_cert_remaining / 86400` (converts to days) per domain as a bar chart

## Set up alerts

Each monitor supports only one metric. Create a separate monitor for each alert scenario below.

### Endpoint down

1. Go to **Alerting → Monitors** and click **New monitor → Metrics**.
2. Click **+ Add metric** and select `httpcheck_status`.
3. In the **FILTERS** section, add `http_url::str` with your endpoint URL (e.g. `"https://api.example.com/health"`) and `http_status_class::str` with `"2xx"`. This scopes the monitor to one endpoint and evaluates only the successful status-class series.
4. In **Trigger conditions**, set **Min allowed number** to `1` — fires when the value drops below 1 (endpoint down).
5. Set **Check the last** to 2–3× your `collection_interval` to avoid alerts on transient failures.
6. Choose a [notification channel](/features/alerting/notifications).

### Response validation failed

1. Go to **Alerting → Monitors** and click **New monitor → Metrics**.
2. Click **+ Add metric** and select `httpcheck_validation_failed`.
3. Filter by `http_url::str` to scope the monitor to one endpoint.
4. In **Trigger conditions**, set **Max allowed number** to `0` — fires when any validation failure is recorded.

### Certificate expiring soon

1. Go to **Alerting → Monitors** and click **New monitor → Metrics**.
2. Click **+ Add metric** and select `httpcheck_tls_cert_remaining`.
3. Set **Min allowed number** to `2592000` — fires when fewer than 30 days (in seconds) remain before expiry.

## See also

- [HTTPcheck receiver full reference](/guides/opentelemetry-httpcheck) — authentication, all validation types, per-phase timing metrics
- [Metric monitors](/features/alerting/metric-monitors) — full alerting configuration reference
- [Kubernetes monitoring](/get/kubernetes) — add cluster health monitoring alongside endpoint checks