Oracle Cloud Infrastructure Documentation

Getting Started With the Health Checks API

The Health Checks service allows you to configure and deploy monitors and on-demand probes using the Health Checks API. Use the following guide to learn how to set up monitors and probes, and retrieve their results using the REST API.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up A collection of users who all need a particular type of access to a set of resources or compartment., A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization., and An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

Endpoints

The Health Checks API can be accessed via the following endpoints:

  • https://healthchecks.ca-toronto-1.oraclecloud.com/20180501
  • https://healthchecks.us-ashburn-1.oraclecloud.com/20180501
  • https://healthchecks.us-phoenix-1.oraclecloud.com/20180501
  • https://healthchecks.eu-frankfurt-1.oraclecloud.com/20180501
  • https://healthchecks.uk-london-1.oraclecloud.com/20180501

Available Protocols For Probes and Monitors

You can configure monitors and probes to use HTTP or ping requests. You will need to ensure that the endpoint being monitored is configured to accept the specified protocol.

HTTP - Configure a GET or HEAD request using HTTP/1.1 to test the target for availability. The probe results are returned in JSON and include the HTTP Status Code and DNS lookup, connection and response timings.

HTTPS - Configure an encrypted HTTPS GET or HEAD request to test the availability of any secure hosted target. Defaults to port 443. The probe results are returned in JSON and include the HTTP Status Code and DNS lookup, connection and response timings.

ICMP - Configure an ICMP echo request ping. The results include the round trip time (RTT) latency.

TCP - Configure a TCP handshake to the specified end point. You should be sure to own this endpoint as testing this connection can be costly to the recipient. The results include the round trip time (RTT) latency.

Create A Monitor

Monitors allow you to monitor the health of endpoints over time. The following example shows how to create an HTTPS monitor that checks the health of www.example.com at an interval of every 30 seconds using a GET request.

POST /20180501/httpMonitors
 
				{
				"compartmentId": "ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
				"protocol": "HTTPS",
				"port": 443,
				"targets": [
				"www.example.com"
				],
				"timeoutInSeconds": 30,
				"method": "GET",
				"displayName": "Example HTTP monitor",
				"intervalInSeconds": 30
		}

Targets can be either hostnames or IP addresses, and the path field can be used to specify an optional path, such as www.example.com/project/help.htm. Optionally, you can specify which geographic locations you would like the monitor to launch from by using the vantagePointNames field. At least one vantage point must be listed when using this field. For a list of available vantage points, see Vantage Points.

A 200 response will be returned with the successful creation of a probe, and the results of the probe can be retrieved from the URL in the resultsUrl field of the response.

{
				"id": "ocid1.httpmonitor.OC2...abuxgljr6l4nepxjkmbtnibwqpu5z24xdvmr7okzoi47wicoflrxh32rwd7a",
				"compartmentId": "ocid1.compartment.oc1..aaaaaaacsxgoz7flzmry5dr6scf7xru6lwqpoygqld74npvn5rdj2cv3iiq",
				"resultsUrl": "https://healthchecks.us-ashburn-1.oraclecloud.com/20180501/httpProbeResults/ocid1.httpmonitor.OC2...abuxgljr6l4nepxjkmbtnibwqpu5z24xdvmr7okzoi47wicoflrxh32rwd7a",
				"targets": [
				"www.example.com",
				"www.oracle.com"
				],
				"vantagePointNames": [
				"ibm-sjc",
				"aws-dub",
				"dgo-nyc"
				],
				"protocol": "HTTPS",
				"timeoutInSeconds": 30,
				"displayName": "Example Monitor",
				"intervalInSeconds": 30,
				"isEnabled": true
		}

For more information about creating an HTTP monitor, see CreateHttpMonitor.

Note

You can configure a similar style monitors using TCP or ICMP protocols. For more information, see CreatePingMonitor.

Create An On-Demand Probe

Probes are one-off health assessments of an endpoint that can be deployed at anytime. The following example shows how to create an on-demand HTTP probe that checks the health of www.example.com with a GET request.

POST /20180501/httpProbeResults
 
{
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
  "protocol": "HTTP",
  "targets": [
      "www.example.com"
  ],
  "timeoutInSeconds": 30,
  "method": "GET"
}

Targets can be either hostnames or IP addresses, and the path field can be used to specify an optional path, such as www.example.com/project/help.htm. Additionally, you can specify which geographic locations you would like the probe to launch from by using the vantagePointNames field. For a list of available vantage points, see Vantage Points.

A 200 response will be returned with the successful creation of a probe, and the results of the probe can be retrieved from the URL in the resultsUrl field of the response. It will take a few moments for results to display once the tests have been configured.

{  
   "id":"ocid1.pingprobe.OC2...abuxgljr6l4nepxjkmbtnibwqpu6y34xdvmr7okzoi47wicoflrxh32rwd9z",
   "compartmentId":"ocid1.compartment.oc1..aaaaaaacsxgoz7flzmry5dr6scf7xru6lwqpoygqld74npvn5rdj2cv3iiq",
   "resultsUrl":"https://healthchecks.us-ashburn-1.oraclecloud.com/20180501/pingProbeResults/ocid1.pingprobe.OC2...abuxgljr6l4nepxjkmbtnibwqpu6y34xdvmr7okzoi47wicoflrxh32rwd9z",
   "targets":[  
      "www.example.com"
   ],
   "vantagePointNames":[  
      "ibm-sjc",
      "aws-dub",
      "dgo-nyc"
   ],
   "protocol":"ICMP",
   "timeoutInSeconds":30
}

For more information about creating a probe, see CreateOnDemandHttpProbe.

Note

You can configure similar style probes using TCP or ICMP protocols. For more information, see CreateOnDemandPingProbe.

Retrieving Probe And Monitor Results

Probe and monitor results can be retrieved from URL in the resultsUrl field of a monitor or probe creation response. It will take a few moments for results to display once the tests have been configured. Results can also be retrieved at anytime using the following methods:

Retrieving results for an on-demand probe or monitor requires the probe or monitor's configuration ID as a parameter. On-demand probe and configuration IDs are assigned upon their creation and are returned in the id field of the POST response. You can also use the ListHttpMonitor method to retrieve a list of currently configured monitors and probes using HTTP protocols. Use the ListPingMonitors method to retrieve a list of currently configured monitors and probes using TCP and ICMP protocols.

The following is an example of results retrieved using GET /httpProbeResults/{probeConfigurationId}.

{  
  "key": "651b9f3a46041cace0530204060ae27e",
  "probeConfigurationId": "ocid1.httpmonitor.OC2...abuxgljr6l4nepxjkmbtnibwqpu5z24xdvmr7okzoi47wicoflrxh32rwd7a",
  "startTime": 1517323711505,
  "target": "www.example.com",
  "vantagePointName": "dgo-nyc",
  "protocol": "HTTPS",
  "connection": {
    "connectDuration": 114,
    "secureConnectDuration": 99,
    "address": "93.184.216.34",
    "port": 443
    },
  "dns":{
    "domainLookupDuration": 29,
    "addresses": [
      "93.184.216.34",
      "2606:2800:220:1:248:1893:25c8:1946"
      ]
      },
  "statusCode": 200,
  "fetchStart": 1517323711505,
  "domainLookupStart": 1517323711505,
  "domainLookupEnd": 1517323711534,
  "connectStart": 1517323711535,
  "secureConnectionStart": 1517323711550,
  "connectEnd": 1517323711649,
  "requestStart": 1517323711649,
  "responseStart": 1517323711673,
  "responseEnd": 1517323711676,
  "duration": 171,
  "encodedBodySize": 1270,
  "isTimedOut": false,
  "isHealthy": true
}

Vantage Points

Vantage points are geographic locations from which monitors and probes can be launched. Oracle Cloud Infrastructure maintains vantage points on the infrastructure of cloud providers around the world, including AWS, IBM, and Azure. The list below is a sampling of the vantage points available. The list of vantage points is dynamic and changes frequently. Use the ListHealthChecksVantagePoints method to return a list of available vantage points.

Provider Location Name
Amazon Singapore aws-sin
Amazon Sao Paolo aws-sao
Amazon Dublin aws-dub
Amazon San Francisco aws-sfo
Azure Dublin azr-dub
Azure Amsterdam azr-ams
Azure Singapore azr-sin
Azure Sydney azr-syd
Digital Ocean Toronto dgo-yyz
Digital Ocean Frankfurt dgo-fra
Digital Ocean New York City dgo-nyc
Digital Ocean Biratnagar, Nepal dgo-blr
Google Taiwan goo-tpe
Google Brussels goo-bru
Google Council Bluffs, IA goo-cbf
Google Charleston, SC goo-chs
IBM San Jose, CA ibm-sjc
IBM Tokyo ibm-hnd
IBM Dallas, TX ibm-dfw
IBM Hong Kong ibm-hkg
Rack Space Ashburn, VA rck-iad
Rack Space Dallas, TX rck-dfw
Rack Space London rck-lhr
Rack Space Sydney rck-syd