PingAccess

Heartbeat endpoint

The heartbeat endpoint verifies that the PingAccess server is running and, depending on your security settings, can display configuration details.

/pa/heartbeat.ping

This endpoint returns a 200 HTTP status code and a message body of OK if the target PingAccess server is up and functional. You can customize the message by modifying a PingAccess property and a Velocity template file. Learn more in Customizing the heartbeat message.

If a GET request receives a connection error or an HTTP status code other than 200, the server associated with the endpoint is down or malfunctioning.

Load balancers can use the heartbeat endpoint to determine PingAccess’s status.

Making a heartbeat call

You can make a heartbeat call to any active PingAccess listener and on any node in a PingAccess cluster. For example, with default port configurations:

  • A clustered console replica responds to this endpoint on port 9000.

  • A clustered engine responds on port 3000.

The URL should begin with the server name and the PingAccess runtime port number. For example, https://hostname:3000/pa/heartbeat.ping.

If you selected the Use context root as reserved resource base path check box on your PingAccess application, this feature creates an instance of any reserved PingAccess resources under the application’s context root. As such, the context root of the application needs to prepend the reserved context application root (/pa by default) in any file paths that reference it.

If the context root of your application is myApp, the path to the heartbeat endpoint would be myApp/pa/heartbeat.ping and the URL would be https://hostname:3000/myApp/pa/heartbeat.ping instead.

Calls to this endpoint can be logged in the audit log. You can enable heartbeat call logging using the /httpConfig/monitoring administrative endpoint. Learn more in Administrative API endpoints.

Interpreting the results

The heartbeat endpoint can return either a short or detailed status for the target PingAccess server, based on the value of the enable.detailed.heartbeat.response property in the run.properties file. The default value is false.

  • If enable.detailed.heartbeat.response is set to false and the PingAccess instance is running, the endpoint returns an HTTP 200 status code and a message body of OK.

  • If enable.detailed.heartbeat.response is set to true and the PingAccess instance is running, the endpoint returns a configurable status with additional details. The response output format is an Apache Velocity template defined in <PA_HOME>/conf/template/heartbeat.page.json. You can modify this template to suit your needs. Learn more in Customizing the heartbeat message.

  • If the endpoint returns an error, this indicates that the PingAccess instance associated with the endpoint is down.