Monitors

Overview

Cloudflare health checks track the health of pools. They are configured through monitors, which define what type of health check to run and how frequently to run them. Cloudflare monitors your servers from each of our data centers.

Health checks that result in a status change for an origin server are recorded as events in the Load Balancing event logs. You can create, attach, and configure health checks from either the Load Balancing dashboard or the Cloudflare API.


Important notes

  • Availability monitoring checks the health of origin servers every 15 seconds. It reports results via email notifications and the Cloudflare API.
  • The default retry rate is 5 retries/second and is completely configurable. We do not recommend increasing the retry rate significantly. Retries use exponential backoff (1, 2, 4, 8, 16 seconds by default).
  • You can configure monitoring for specific URLs by sending periodic HTTP requests to the load balancer, taking advantage of customizable intervals, timeouts, and status codes. Once an origin server is marked unhealthy, multi-region failover reroutes traffic to the next available server in failover order.
  • Load Balancing monitors use the following HTTP user-agent: "Mozilla/5.0 (compatible; Cloudflare-Traffic-Manager/1.0; +https://www.cloudflare.com/traffic-manager/; pool-id: $poolid)". The $poolid contains the first 16 characters of the Load Balancing pool that is the target of the health check.
  • To prevent health checks from failing, and to secure user infrastructure against spoofed checks from bad actors, we recommend the following:
    • Only accept connections to hosts listed in the Cloudflare IP ranges in your firewall or web-server.
    • Use Cloudflare's user agent (see below) to reject HTTP requests that don't come from these ranges.
    • Ensure that your firewall or web server does not block or rate limit Cloudflare health checks.
  • To configure a monitor on an endpoint behind Basic authentication, configure the proper Authorization header with the value Basic BASE64(username:password). For example, Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

Properties

Monitors support a great deal of customization and have the following properties:

Name/typeDescription/exampleConstraints
port
integer

Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443).

8080
  • default value: 0
method
string

The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks.

"GET"
  • default value: GET
timeout
integer

The timeout (in seconds) before marking the health check as failed

3
  • default value: 5
path
string

The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors.

"/health"
  • default value: /
interval
integer

The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations.

90
  • default value: 60
retries
integer

The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.

0
  • default value: 2
follow_redirects
boolean

Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors.

true
  • default value: false
  • valid values: (true,false)
probe_zone
string

(known as Simulate Zone in the UI) pushes a request from Cloudflare Health Monitors through the Cloudflare stack as if it were a real visitor request to help analyze behavior or validate a configuration. It allows you to emulate the specified zone while probing.

expected_body
string

A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors.

The sub-string must appear within the first 10KiB of your response body.

"alive"
header
object

The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors.

{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }
allow_insecure
boolean

Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors.

true
  • default value: false
  • valid values: (true,false)
modified_on
string (date-time)

Last modification time

"2014-01-01T05:20:00.12345Z"
  • read only
created_on
string (date-time)

Creation time

"2014-01-01T05:20:00.12345Z"
  • read only
type
string

The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'.

"https"
  • default value: http
id
string

API item identifier tag

"f1aba936b94213e5b8dca0c0dbf1f9cc"
  • max length: 32
  • read only
description
string

Object description

"Login page monitor"
    expected_codes
    string

    The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors.

    "2xx"
    • default value: 200

    Managing monitors via the Load Balancing dashboard

    Use the Create Load Balancer or Edit Load Balancer panels in the Load Balancing dashboard to manage health check monitors. For step-by-step guidance, see Create, attach, and configuring health checks.


    Managing monitors via the Cloudflare API

    Use the load_balancers/monitors endpoint to manage monitors via the Cloudflare API.

    Commands

    The Cloudflare API supports the following commands for monitors. (Examples are given for user-level endpoint but apply to the account-level endpoint as well.) For more detail, see Cloudflare API: Load Balancer Monitors.

    CommandMethodEndpoint
    Create MonitorPOSTuser/load_balancers/monitors
    Delete MonitorDELETEuser/load_balancers/monitors
    List MonitorsGETuser/load_balancers/monitors
    Monitor DetailsGETuser/load_balancers/monitors/:identifier
    Update MonitorPUTuser/load_balancers/monitors

    Health Check integration with PagerDuty

    To integrate Cloudflare Health Check notifications with PagerDuty, follow the steps outlined in PagerDuty’s Email Integration Guide. If you do not have a PagerDuty account, you will first need to set that up.

    PagerDuty will generate an email address that will create incidents based on emails sent to that address.

    If you already have email integration configured in PagerDuty, you can find the designated email address by going to Configuration > Services > Email (under Integrations).

    monitors 1

    When creating the Notifier object, configure the email to go to the PagerDuty integration email. Consequently, whenever a pool or origin goes down, an Incident will be created to capture it.

    monitors 2