PingAccess

Heartbeat endpoint

The heartbeat endpoint verifies that the PingAccess server is running and, depending on security settings, displays details about the configuration.

You can make this 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, and a clustered engine responds to it on port 3000.

/pa/heartbeat.ping

This endpoint returns a short or detailed status for the target PingAccess server, based on the value of the enable.detailed.heartbeat.response parameter in run.properties. Load balancers can use this endpoint to determine the status of PingAccess.

The Uniform Resource Locator (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.

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

If enable.detailed.heartbeat.response is set to false, the default value, and the PingAccess instance is running, the endpoint returns an HTTP 200 status and the text OK.

If enable.detailed.heartbeat.response is set to true and the PingAccess instance is running, a configurable status with additional details is returned. 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. The following values are available.

Table
Value Description

$monitor.getTotalJvmMemory('bytes'|'KB'|'MB'|'GB')

Returns the total memory in the Java Virtual Machine (JVM). Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getUsedJvmMemory('bytes'|'KB'|'MB'|'GB')

Returns the used memory in the JVM. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getFreeJvmMemory('bytes'|'KB'|'MB'|'GB')

Returns the free memory in the JVM. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getTotalPhysicalSystemMemory('bytes'|'KB'|'MB'|'GB')

Returns the total system memory. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getTotalUsedPhysicalSystemMemory('bytes'|'KB'|'MB'|'GB')

Returns the used system memory. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getTotalFreePhysicalSystemMemory('bytes'|'KB'|'MB'|'GB')

Returns the free system memory. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. If you don’t specify the units, 'bytes' is the default value.

$monitor.getHostname()

Returns the host name for the system running PingAccess.

$monitor.getNumberOfCpus()

Returns the number of CPU cores in the system.

$monitor.getCpuLoad('###.##')

Returns the current CPU utilization. The parameter contains an optional format value:

  • If the format is specified, the value returned is returned as a percentage value from 0%-100%, formatted using the Java DecimalFormat specification.

  • If no format value is specified, then the value returned is a real number from 0 to 1 which represents the CPU utilization percentage.

For example, a format value of '###.##' will return a value similar to '56.12', but no specified format would cause the value to be returned as '0.5612'.

$monitor.getOpenClientConnections()

Returns the current number of clients connected to PingAccess.

$monitor.getNumberOfVirtualHosts()

Returns the current number of configured virtual hosts in PingAccess.

$monitor.getNumberOfApplications()

Returns the current number of configured applications in PingAccess.

$monitor.getNumberOfSites()

Returns the current number of configured sites in the PingAccess configuration database. In a clustered environment, on the engine nodes, this number will reflect the number of sites associated with applications rather than the number of configured sites that show on the admin node.

For more information, see the Clustering in PingAccess documentation. This value is not included in the default template but can be added by the system administrator if desired.

$monitor.getLastRefreshTime('yyyy/MM/dd HH:mm:ss')

Returns the time that the PingAccess configuration was last refreshed.

The parameter specifies the date format to use:

  • If no value is specified, the ISO 8601 date format is used.

  • If the parameter is specified, the format used comes from the Joda DateTimeFormat specification.

The default content type for the output is application/json. However, you can specify a content type header using the $monitor.setContentType() line in the template.

If you update the enable.detailed.heartbeat.response value, you must restart PingAccess for the new value to take effect.

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