IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« TCP options Configure the task scheduler »

› › ›

HTTP options

edit

HTTP options

edit

Also see Common monitor options.

The options described here configure Heartbeat to connect via HTTP and optionally verify that the host returns the expected response.

Example configuration:

- type: http
  id: myhost
  name: My HTTP Host
  schedule: '@every 5s'
  hosts: ["http://myhost:80"]

`hosts`

edit

A list of URLs to ping.

`max_redirects`

edit

The total number of redirections Heartbeat will follow. Defaults to 0, meaning heartbeat will not follow redirects, but will report the status of the redirect. If set to a number greater than 0 heartbeat will follow that number of redirects.

When this option is set to a value greater than zero the monitor.ip field will no longer be reported, as multiple DNS requests across multiple IPs may return multiple IPs. Fine grained network timing data will also not be recorded, as with redirects that data will span multiple requests. Specifically the fields http.rtt.content.us, http.rtt.response_header.us, http.rtt.total.us, http.rtt.validate.us, http.rtt.write_request.us and dns.rtt.us will be omitted.

`proxy_url`

edit

The HTTP proxy URL. This setting is optional. Example http://proxy.mydomain.com:3128

`username`

edit

The username for authenticating with the server. The credentials are passed with the request. This setting is optional.

You need to specify credentials when your check.response settings require it. For example, you can check for a 403 response (check.response.status: [403]) without setting credentials.

`password`

edit

The password for authenticating with the server. This setting is optional.

`ssl`

edit

The TLS/SSL connection settings for use with the HTTPS endpoint. If you don’t specify settings, the system defaults are used.

Example configuration:

- type: http
  id: my-http-service
  name: My HTTP Service
  hosts: ["https://myhost:443"]
  schedule: '@every 5s'
  ssl:
    certificate_authorities: ['/etc/ca.crt']
    supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"]

Also see SSL for a full description of the ssl options.

`response`

edit

Controls the indexing of the HTTP response body contents to the http.response.body.contents field.

Set response.include_body to one of the options listed below.

on_error: Include the body if an error is encountered during the check. This is the default.
never: Never include the body.
always: Always include the body with checks.

Set response.include_body_max_bytes to control the maximum size of the stored body contents. Defaults to 1024 bytes.

`check`

edit

An optional request to send to the remote host and the expected response.

Example configuration:

- type: http
  id: my-http-host
  name: My HTTP Service
  hosts: ["http://myhost:80"]
  check.request.method: HEAD
  check.response.status: [200]
  schedule: '@every 5s'

Under check.request, specify these options:

method: The HTTP method to use. Valid values are "HEAD", "GET" and "POST".
headers: A dictionary of additional HTTP headers to send. By default heartbeat will set the User-Agent header to identify itself.
body: Optional request body content.

Example configuration: This monitor POSTs an x-www-form-urlencoded string to the endpoint /demo/add

- type: http
  id: demo-service
  name: Demo Service
  schedule: '@every 5s'
  urls: ["http://localhost:8080/demo/add"]
  check.request:
    method: POST
    headers:
      'Content-Type': 'application/x-www-form-urlencoded'
    # urlencode the body:
    body: "name=first&email=someemail%40someemailprovider.com"
  check.response:
    status: [200]
    body:
      - Saved
      - saved

Under check.response, specify these options:

status: A list of expected status codes. 4xx and 5xx codes are considered down by default. Other codes are considered up.
headers: The required response headers.
body: A list of regular expressions to match the body output. Only a single expression needs to match. HTTP response bodies of up to 100MiB are supported.

Example configuration: This monitor examines the response body for the strings saved or Saved and expects 200 or 201 status codes

- type: http
  id: demo-service
  name: Demo Service
  schedule: '@every 5s'
  urls: ["http://localhost:8080/demo/add"]
  check.request:
    method: POST
    headers:
      'Content-Type': 'application/x-www-form-urlencoded'
    # urlencode the body:
    body: "name=first&email=someemail%40someemailprovider.com"
  check.response:
    status: [200, 201]
    body:
      - Saved
      - saved

json: A list of condition expressions executed against the body when parsed as JSON. Body sizes must be less than or equal to 100 MiB.

The following configuration shows how to check the response when the body contains JSON:

- type: http
  id: demo-service
  name: Demo Service
  schedule: '@every 5s'
  hosts: ["https://myhost:80"]
  check.request:
    method: GET
    headers:
      'X-API-Key': '12345-mykey-67890'
  check.response:
    status: [200]
    json:
      - description: check status
        condition:
          equals:
            status: ok

The following configuration shows how to check the response for multiple regex patterns:

- type: http
  id: demo-service
  name: Demo Service
  schedule: '@every 5s'
  hosts: ["https://myhost:80"]
  check.request:
    method: GET
    headers:
      'X-API-Key': '12345-mykey-67890'
  check.response:
    status: [200]
    body:
      - hello
      - world

The following configuration shows how to check the response with a multiline regex:

- type: http
  id: demo-service
  name: Demo Service
  schedule: '@every 5s'
  hosts: ["https://myhost:80"]
  check.request:
    method: GET
    headers:
      'X-API-Key': '12345-mykey-67890'
  check.response:
    status: [200]
    body: '(?s)first.*second.*third'

« TCP options Configure the task scheduler »