Monitor HTTP endpoints with Uptrace

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.

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

Go to Alerting → Monitors and click New monitor → Metrics.
Click + Add metric and select httpcheck_status.
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.
In Trigger conditions, set Min allowed number to 1 — fires when the value drops below 1 (endpoint down).
Set Check the last to 2–3× your collection_interval to avoid alerts on transient failures.
Choose a notification channel.

Response validation failed

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

Certificate expiring soon

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