Configuring Canary App Health Endpoint

This topic describes how to use the Pivotal Healthwatch API to do view or update the canary app health URL for your Tanzu Application Service (TAS for VMs) deployment.

For more information about this metric, see Canary App Health in Pivotal Healthwatch Metrics.

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 in Installing Pivotal Healthwatch. For an example of generating and using a UAAC token for API calls, see Using the Ops Manager API in the Ops Manager documentation.

Check Healthwatch API Status

To check the availability of the Healthwatch API, run:

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

Where SYSTEM-DOMAIN is the system domain URL configured in the TAS for VMs tile. For example, sys.example.com.

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:

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

Where SYSTEM-DOMAIN is the system domain URL configured in the TAS for VMs tile. For example, sys.example.com.

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 Pivotal Application Service v2.4 Release Notes. cf-GUID is shown on the healthwatch.SYSTEM-DOMAIN/diego/capacity page, where SYSTEM-DOMAIN is the system domain URL configured in the TAS for VMs tile.

This returns a JSON object in the following format:

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

Where CONFIGURED-CANARY-URL is the currently configured canary URL.

Update Canary URL

POST /v1/canary?deployment=cf-GUID

To update the canary URL for a deployment, run:

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

Where:

  • SYSTEM-DOMAIN is the system domain URL configured in the TAS for VMs tile. For example, sys.example.com.

  • CANARY-URL is the URL you want to have checked for HTTP 200 responses.

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.