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.

Properties

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

Name /type Description /example Constraints
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)
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.

        Command Method Endpoint
        Create Monitor POST user/load_balancers/monitors
        Delete Monitor DELETE user/load_balancers/monitors
        List Monitors GET user/load_balancers/monitors
        Monitor Details GET user/load_balancers/monitors/:identifier
        Update Monitor PUT user/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).

        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.