httpcheckreceiver

HTTP Check Receiver

Status
Stability	alpha: metrics
Distributions	contrib, k8s
Issues
Code coverage
Code Owners	@VenuEmmadi | Seeking more code owners!
Emeritus	@codeboten

The HTTP Check Receiver can be used for synthetic checks against HTTP endpoints. 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

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:
  httpcheck:
    metrics:
      httpcheck.tls.cert_remaining:
        enabled: true

Timing Breakdown Metrics

For detailed performance analysis, timing breakdown metrics are available:

receivers:
  httpcheck:
    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:
  httpcheck:
    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:
  httpcheck:
    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:
  httpcheck:
    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:
  httpcheck:
    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: [httpcheck]
      exporters: [debug]

Metrics

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