Httpcheck Receiver

Available in: contrib, k8s Maintainers: @VenuEmmadi Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

This receiver will make a request to the specified endpoint using the configured method. This scraper generates a metric with a label for each HTTP response status class with a value of 1 if the status code matches the class. For example, the following metrics will be generated if the endpoint returned a 200:

httpcheck.status{http.status_class:1xx, http.status_code:200,...} = 0
httpcheck.status{http.status_class:2xx, http.status_code:200,...} = 1
httpcheck.status{http.status_class:3xx, http.status_code:200,...} = 0
httpcheck.status{http.status_class:4xx, http.status_code:200,...} = 0
httpcheck.status{http.status_class:5xx, http.status_code:200,...} = 0

For HTTPS endpoints, the receiver can collect TLS certificate metrics including the time remaining until certificate expiry. This allows monitoring of certificate expiration alongside HTTP availability. Note that TLS certificate metrics are disabled by default and must be explicitly enabled in the metrics configuration.

Configuration

Note: This receiver was renamed from httpcheck to http_check to match the snake_case naming convention. The deprecated component type httpcheck is still accepted as an alias and will log a deprecation warning.

The following configuration settings are available:

targets (required): The list of targets to be monitored.
collection_interval (optional, default = 60s): This receiver collects metrics on an interval. Valid time units are ns, us (or µs), ms, s, m, h.
initial_delay (optional, default = 1s): defines how long this receiver waits before starting.

Each target has the following properties:

endpoint (optional): A single URL to be monitored.
endpoints (optional): A list of URLs to be monitored.
method (optional, default: GET): The HTTP method used to call the endpoint or endpoints.
body (optional): Request body content for POST, PUT, PATCH, and other methods.

At least one of endpoint or endpoints must be specified. Additionally, each target supports the client configuration options of confighttp.

Optional Metrics

The receiver provides optional metrics that are disabled by default and can be enabled in the configuration:

TLS Certificate Monitoring

For HTTPS endpoints, TLS certificate metrics can be enabled:

receivers:
  http_check:
    metrics:
      httpcheck.tls.cert_remaining:
        enabled: true

Timing Breakdown Metrics

For detailed performance analysis, timing breakdown metrics are available:

receivers:
  http_check:
    metrics:
      httpcheck.dns.lookup.duration:
        enabled: true
      httpcheck.client.connection.duration:
        enabled: true
      httpcheck.tls.handshake.duration:
        enabled: true
      httpcheck.client.request.duration:
        enabled: true
      httpcheck.duration:
        enabled: true
      httpcheck.response.duration:
        enabled: true

These metrics provide detailed timing information for different phases of the HTTP request:

dns.lookup.duration: Time spent performing DNS lookup
client.connection.duration: Time spent establishing TCP connection
tls.handshake.duration: Time spent performing TLS handshake (HTTPS only)
client.request.duration: Time spent sending the HTTP request
response.duration: Time spent receiving the HTTP response

Response Validation Metrics

For API monitoring and health checks, response validation metrics are available:

receivers:
  http_check:
    metrics:
      httpcheck.validation.passed:
        enabled: true
      httpcheck.validation.failed:
        enabled: true
      httpcheck.response.size:
        enabled: true

These metrics track validation results with validation.type attribute indicating the validation type (contains, json_path, size, regex).

Request Body Support

The receiver supports sending request bodies for POST, PUT, PATCH, and other HTTP methods:

receivers:
  http_check:
    targets:
      # POST with JSON body
      - endpoint: "https://api.example.com/users"
        method: "POST"
        body: '{"name": "John Doe", "email": "[email protected]"}'
        
      # PUT with form data
      - endpoint: "https://api.example.com/profile"
        method: "PUT"
        body: "name=John&[email protected]"
        
      # PATCH with custom Content-Type
      - endpoint: "https://api.example.com/settings"
        method: "PATCH"
        body: '{"theme": "dark"}'
        headers:
          Content-Type: "application/json"
          Authorization: "Bearer token123"

Content-Type Auto-Detection:

JSON bodies (starting with { or [): application/json
Form data (containing =): application/x-www-form-urlencoded
Other content: text/plain
Custom headers override auto-detection

Response Validation

The receiver supports response body validation for API monitoring:

receivers:
  http_check:
    targets:
      - endpoint: "https://api.example.com/health"
        validations:
          # String matching
          - contains: "healthy"
          - not_contains: "error"
          
          # JSON path validation using gjson syntax
          - json_path: "$.status"
            equals: "ok"
          - json_path: "$.services[*].status"
            equals: "up"
          
          # Response size validation (bytes)
          - max_size: 1024
          - min_size: 10
          
          # Regex validation
          - regex: "^HTTP/[0-9.]+ 200"

Validation Types:

contains / not_contains: String matching
json_path + equals: JSON path queries using gjson syntax
max_size / min_size: Response body size limits
regex: Regular expression matching

Example Configuration

receivers:
  http_check:
    collection_interval: 30s
    # Optional: Enable timing breakdown metrics
    metrics:
      httpcheck.dns.lookup.duration:
        enabled: true
      httpcheck.client.connection.duration:
        enabled: true
      httpcheck.tls.handshake.duration:
        enabled: true
      httpcheck.client.request.duration:
        enabled: true
      httpcheck.response.duration:
        enabled: true
      httpcheck.tls.cert_remaining:
        enabled: true
      httpcheck.validation.passed:
        enabled: true
      httpcheck.validation.failed:
        enabled: true
      httpcheck.response.size:
        enabled: true
    targets:
      - method: "GET"
        endpoints:
          - "https://opentelemetry.io"
      - method: "GET"
        endpoints: 
          - "http://localhost:8080/hello1"
          - "http://localhost:8080/hello2"
        headers:
          Authorization: "Bearer <your_bearer_token>"
      - method: "GET"
        endpoint: "http://localhost:8080/hello"
        headers:
          Authorization: "Bearer <your_bearer_token>"
      - method: "POST"
        endpoint: "https://api.example.com/users"
        body: '{"name": "Test User", "email": "[email protected]"}'
      - method: "GET"
        endpoint: "https://api.example.com/health"
        validations:
          - contains: "healthy"
          - json_path: "$.status"
            equals: "ok"
          - max_size: 1024
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    metrics:
      receivers: [http_check]
      exporters: [debug]

Metrics

Details about the metrics produced by this receiver can be found in documentation.md

Metrics

Metric Name	Description	Unit	Type	Attributes
❌ `httpcheck.client.connection.duration`	Time spent establishing TCP connection to the endpoint.	ms	Gauge	http.url, network.transport
❌ `httpcheck.client.request.duration`	Time spent sending the HTTP request to the endpoint.	ms	Gauge	http.url
❌ `httpcheck.dns.lookup.duration`	Time spent performing DNS lookup for the endpoint.	ms	Gauge	http.url
✅ `httpcheck.duration`	Measures the duration of the HTTP check.	ms	Gauge	http.url
✅ `httpcheck.error`	Records errors occurring during HTTP check.	{error}	UpDownCounter	http.url, error.message
❌ `httpcheck.response.duration`	Time spent receiving the HTTP response from the endpoint.	ms	Gauge	http.url
❌ `httpcheck.response.size`	Size of response body in bytes.	By	Gauge	http.url
✅ `httpcheck.status`	1 if the check resulted in status_code matching the status_class, otherwise 0.	1	UpDownCounter	http.url, http.status_code, http.method, http.status_class
❌ `httpcheck.tls.cert_remaining`	Time in seconds until certificate expiry, as specified by `NotAfter` field in the x.509 certificate. Negative values represent time in seconds since expiration.	s	Gauge	http.url, http.tls.issuer, http.tls.cn, http.tls.san
❌ `httpcheck.tls.handshake.duration`	Time spent performing TLS handshake with the endpoint.	ms	Gauge	http.url
❌ `httpcheck.validation.failed`	Number of response validations that failed.	{validation}	UpDownCounter	http.url, validation.type
❌ `httpcheck.validation.passed`	Number of response validations that passed.	{validation}	UpDownCounter	http.url, validation.type

Attributes

Attribute Name	Description	Type
`error.message`	Error message recorded during check	string
`http.method`	HTTP request method	string
`http.status_class`	HTTP response status class	string
`http.status_code`	HTTP response status code	int
`http.tls.cn`	The commonName in the subject of the certificate.	string
`http.tls.issuer`	The entity that issued the certificate.	string
`http.tls.san`	The Subject Alternative Name of the certificate.	slice
`http.url`	Full HTTP request URL.	string
`network.transport`	OSI transport layer or inter-process communication method.	string
`validation.type`	Type of validation performed (contains, json_path, size, regex)	string

Last generated: 2026-04-13

Collector components

​Httpcheck Receiver

​Supported Telemetry

​Overview

​Configuration

​Optional Metrics

​TLS Certificate Monitoring

​Timing Breakdown Metrics

​Response Validation Metrics

​Request Body Support

​Response Validation

​Example Configuration

​Metrics

​Metrics

​Attributes

Httpcheck Receiver

Supported Telemetry

Overview

Configuration

Optional Metrics

TLS Certificate Monitoring

Timing Breakdown Metrics

Response Validation Metrics

Request Body Support

Response Validation

Example Configuration

Metrics

Metrics

Attributes