Configuring Canary App Health Endpoint

This topic describes how to use the Pivotal Healthwatch API to do the following:

  • View the current canary app health URL for the Pivotal Application Service (PAS) deployment.
  • Update the canary app health URL for the PAS deployment.

See the Canary App Health section for more information about this metric.

Prerequisite

The steps in this document require that you generate bearer tokens for a UAA client with the healthwatch.read and healthwatch.admin scopes. For more information on granting these scopes, see Allow Additional Users to Access the Pivotal Healthwatch UI. For an example of generating and using a UAAC token for API calls, see Using the Ops Manager API.

Check Healthwatch API Status

To check the availability of the Healthwatch API, run the following command:

$ curl https://healthwatch-api.SYSTEM-DOMAIN/info

A successful response is a 200/OK with the message "HAPI is happy".

View Canary URL

GET /v1/canary?deployment=cf-GUID

To view the currently configured canary URL, run the following command:

$ uaac curl https://healthwatch-api.SYSTEM-DOMAIN/v1/canary?deployment=cf-GUID

Note: The cf deployment is currently the only supported deployment for the canary url configuration. These endpoints only support deployment names beginning with cf. For more information about the cf deployment metric change, see Changed “deployment” Field Value for PAS Metrics in the PAS v2.4 release notes. cf-GUID is shown on the healthwatch.SYSTEM-DOMAIN/diego/capacity page.

This returns a JSON object in the following format:

  {
    "deployment":"cf-GUID",
    "url":"CONFIGURED CANARY URL"
  }

Update Canary URL

POST /v1/canary?deployment=cf-GUID

To update the canary URL for a deployment, run the following command. Ensure that your URL includes a protocol, such as https.

$ uaac curl -X POST "https://healthwatch-api.SYSTEM-DOMAIN/v1/canary?deployment=cf-GUID" \
      -H "Content-Type: application/json" \
      --data "{\"url\":\"https://SOME-VALID-URL.com\"}"

Understand the Response

See the following table for possible response codes and their explanations.

Response code Explanation
200 A record was updated.
400 A validation error occurred.
500 An error occurred while trying to update the record. Check the logs for the healthwatch-api app.

See the following table for details about the contents of the response payload, which is in JSON format.

Field Explanation
deployment The deployment name.
url The configured canary endpoint.
reachable Boolean indicating whether the endpoint was reachable from the Healthwatch API.
responseBody The response from attempting an HTTP GET request to the canary endpoint.