OpenTelemetry HTTPcheck Receiver

February 14, 2026

5 min read

Learn how to use the OpenTelemetry Collector HTTPcheck receiver to perform synthetic checks against HTTP endpoints, monitor uptime, validate responses, and track TLS certificate expiration.

What is OpenTelemetry Collector?

OpenTelemetry Collector is an agent that pulls telemetry data from systems you want to monitor and exports the collected data to an OpenTelemetry backend.

The Collector provides powerful data processing capabilities, allowing you to perform aggregation, filtering, sampling, and enrichment of telemetry data before sending it to backend systems.

What is the HTTPcheck receiver?

The HTTPcheck receiver is a component of the OpenTelemetry Collector that performs synthetic checks against HTTP endpoints. It makes periodic requests to specified URLs and records metrics about availability, response time, and response content.

Use cases include:

Uptime monitoring - Check if services are reachable and responding
Response validation - Verify response content matches expectations
TLS certificate monitoring - Track certificate expiration dates
Performance tracking - Measure DNS, connection, and response times

Basic configuration

Here's a minimal configuration to monitor an HTTP endpoint:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.uptrace.dev/health/status'
        method: GET
    collection_interval: 60s

processors:
  batch:

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

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

Monitoring multiple endpoints

Check several endpoints with different methods and configurations:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
      - endpoint: 'https://api.example.com/v2/status'
        method: GET
      - endpoint: 'https://staging.example.com/health'
        method: GET
    collection_interval: 30s

Target configuration options

Each target supports the following options:

Option	Type	Default	Description
`endpoint`	string	required	The URL to check
`method`	string	`GET`	HTTP method to use
`headers`	map	-	Additional HTTP headers
`body`	string	-	Request body content
`auto_content_type`	bool	false	Auto-set Content-Type based on body
`timeout`	duration	`10s`	Request timeout
`tls`	object	-	TLS configuration
`auth`	object	-	Authentication configuration

Response validation

Validate response content using rules:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
        validations:
          - contains: '"status":"healthy"'
          - not_contains: '"error"'
          - min_size: 10
          - max_size: 10000

Validation types

Type	Description
`contains`	Response body must contain this string
`not_contains`	Response body must not contain this string
`json_path`	JSON path expression to extract a value
`equals`	Value must match exactly (used with json_path)
`min_size`	Minimum response body size in bytes
`max_size`	Maximum response body size in bytes
`regex`	Regular expression pattern to match

JSON path validation

Validate specific JSON fields in the response:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
        validations:
          - json_path: 'status'
            equals: 'ok'
          - json_path: 'version'
            regex: '^\d+\.\d+\.\d+$'

Authentication

Basic auth

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/internal/health'
        method: GET
        auth:
          authenticator: basicauth

extensions:
  basicauth:
    client_auth:
      username: monitoring
      password: ${env:MONITOR_PASSWORD}

Bearer token

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
        headers:
          Authorization: 'Bearer ${env:API_TOKEN}'

TLS configuration

Monitor HTTPS endpoints with custom TLS settings:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://internal.example.com/health'
        method: GET
        tls:
          insecure_skip_verify: false
          ca_file: /etc/ssl/certs/ca.pem
          cert_file: /etc/ssl/certs/client.pem
          key_file: /etc/ssl/certs/client-key.pem
    collection_interval: 60s

Health Check Extension

You can use the HTTPcheck receiver with the Collector's own Health Check Extension to monitor the Collector itself:

yaml

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

receivers:
  httpcheck:
    targets:
      - endpoint: 'http://localhost:13133/health/status'
        method: GET
    collection_interval: 15s

Metrics reference

Default metrics (enabled)

Metric	Type	Unit	Description
`httpcheck.duration`	Gauge	ms	Total duration of the HTTP check
`httpcheck.status`	Sum	1	1 if status code matches expected class, 0 otherwise
`httpcheck.error`	Sum	count	Count of errors during HTTP checks

Optional metrics (disabled by default)

Enable these in your metrics builder config for detailed timing breakdowns:

Metric	Type	Unit	Description
`httpcheck.dns.lookup.duration`	Gauge	ms	DNS resolution time
`httpcheck.client.connection.duration`	Gauge	ms	TCP connection establishment time
`httpcheck.tls.handshake.duration`	Gauge	ms	TLS handshake time
`httpcheck.client.request.duration`	Gauge	ms	HTTP request transmission time
`httpcheck.response.duration`	Gauge	ms	HTTP response receipt time
`httpcheck.response.size`	Gauge	bytes	Response body size
`httpcheck.tls.cert_remaining`	Gauge	s	Time until TLS certificate expiry
`httpcheck.validation.passed`	Sum	count	Count of successful response validations
`httpcheck.validation.failed`	Sum	count	Count of failed response validations

Metric attributes

Attribute	Metrics	Description
`http.url`	All metrics	The checked URL
`http.method`	`httpcheck.status`	HTTP method used
`http.status_code`	`httpcheck.status`	Response status code
`http.status_class`	`httpcheck.status`	Status class (1xx, 2xx, 3xx, 4xx, 5xx)
`error.message`	`httpcheck.error`	Error description
`http.tls.issuer`	`httpcheck.tls.cert_remaining`	Certificate issuer
`http.tls.cn`	`httpcheck.tls.cert_remaining`	Certificate common name
`http.tls.san`	`httpcheck.tls.cert_remaining`	Subject alternative names
`validation.type`	`httpcheck.validation.*`	Type of validation (contains, regex, etc.)

Enabling optional metrics

To enable optional metrics, add a metrics section to your receiver config:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
    collection_interval: 60s
    metrics:
      httpcheck.dns.lookup.duration:
        enabled: true
      httpcheck.tls.handshake.duration:
        enabled: true
      httpcheck.tls.cert_remaining:
        enabled: true
      httpcheck.response.size:
        enabled: true
      httpcheck.validation.passed:
        enabled: true
      httpcheck.validation.failed:
        enabled: true

Complete example

A production-ready configuration monitoring multiple services with validation and TLS monitoring:

yaml

receivers:
  httpcheck:
    targets:
      - endpoint: 'https://api.example.com/health'
        method: GET
        validations:
          - contains: '"status":"ok"'
      - endpoint: 'https://web.example.com'
        method: GET
        validations:
          - min_size: 1000
          - contains: '</html>'
      - endpoint: 'https://internal.example.com/api/v1/status'
        method: POST
        headers:
          Content-Type: application/json
        body: '{"check": "full"}'
        validations:
          - json_path: 'healthy'
            equals: 'true'
    collection_interval: 60s
    metrics:
      httpcheck.tls.cert_remaining:
        enabled: true
      httpcheck.dns.lookup.duration:
        enabled: true

processors:
  batch:

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

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

OpenTelemetry Backend

Once the metrics are collected and exported, you can visualize them using a compatible backend system. For example, you can use Uptrace to create dashboards that display metrics from the OpenTelemetry Collector.

Uptrace is an open source APM for OpenTelemetry that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.

Uptrace Overview

Uptrace comes with an intuitive query builder, rich dashboards, alerting rules, notifications, and integrations for most languages and frameworks.

Uptrace can process billions of spans and metrics on a single server and allows you to monitor your applications at 10x lower cost.

In just a few minutes, you can try Uptrace by visiting the cloud demo (no login required) or running it locally with Docker. The source code is available on GitHub.

FAQ

What is the HTTPcheck receiver? The HTTPcheck receiver is an OpenTelemetry Collector component that performs synthetic HTTP checks against endpoints. It records metrics about availability, response time, status codes, and can validate response content.

How often should I check endpoints? For production health checks, 30-60 seconds is typical. For critical services, you might use 15 seconds. Avoid very short intervals as they can generate unnecessary load on your services.

Can I validate JSON responses? Yes, use the json_path validation type with equals to check specific fields. For example, json_path: 'status' with equals: 'ok' validates that the JSON response has {"status": "ok"}.

How do I monitor TLS certificate expiration? Enable the httpcheck.tls.cert_remaining metric. It reports the time remaining in seconds until certificate expiry. Negative values indicate an expired certificate. Set up alerts when the value drops below 30 days (2592000 seconds).

What happens when a check fails? Failed checks increment the httpcheck.error metric with an error.message attribute describing the failure. The httpcheck.status metric will report 0 for the expected status class.

Can I use POST requests with a body? Yes, specify method: POST and provide a body string. Use auto_content_type: true to automatically detect the content type, or set it manually via headers.

What's next?

HTTP endpoint monitoring is now active, providing uptime checks and response time metrics for your services. Combine with Kubernetes monitoring for cluster health checks, or add Docker instrumentation for containerized service monitoring. Set up the OpenTelemetry Collector for additional receivers and processing pipelines.