PingAccess

Customizing the heartbeat message

The heartbeat endpoint, /pa/heartbeat.ping, returns a 200 HTTP status code and a customizable OK browser message if the PingAccess server is running.

You can customize the amount of detail included in the browser message by modifying the enable.detailed.heartbeat.response PingAccess property.

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

Steps

  1. To configure the heartbeat response level, make the following changes to the <PA_HOME>/conf/run.properties file.

    Learn more about the following properties in the monitoring section of the Configuration file reference.

    1. To configure the level of detail included in the heartbeat response, set the enable.detailed.heartbeat.response property to true or false.

      While the PingAccess server is running, calls to the heartbeat endpoint result in the following behavior, depending on the value of this property:

      false (default)

      The /pa/heartbeat.ping endpoint returns only the HTTP status code and OK message.

      true

      The /pa/heartbeat.ping endpoint returns all available statistics. The response output format is an Apache Velocity template defined in <PA_HOME>/conf/template/heartbeat.page.json.

      Before exposing these additional statistics on the heartbeat endpoint, ensure the endpoint cannot be reached beyond the load balancer so this information isn’t made publicly available.

    2. If enable.detailed.heartbeat.response is set to true, enter a value for the pa.statistics.window.seconds property to establish how long PingAccess should spend collecting statistics before providing the heartbeat response.

    3. You must restart PingAccess for changes to the run.properties file to take effect.

  2. To customize the heartbeat template, edit the heartbeat.page.json file, located in the <PA_HOME>/conf/template directory.

    The following template values are available for modification.

    Template values
    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. The default value is 'bytes'.

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

    Returns the used memory in the JVM.

    Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. The default value is 'bytes'.

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

    Returns the free memory in the JVM. Enter 'bytes', 'KB', 'MB', or 'GB' to specify the units. The default value is 'bytes'.

    $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.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.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.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 CPU utilization. The parameter contains an optional format value:

    • If the format is specified, the value returned is 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 number of clients connected to PingAccess.

    $monitor.getNumberOfVirtualHosts()

    Returns the number of configured virtual hosts in PingAccess.

    $monitor.getNumberOfApplications()

    Returns the number of configured applications in PingAccess.

    $monitor.getNumberOfSites()

    Returns the 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.

    You can find more information in the Clustering in PingAccess documentation.

    This value isn’t 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 informs which date format to use:

    • If the parameter isn’t 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.

    1. To specify percentiles in addition to, or in place of, the default 90th percentile in the statistics reported on the heartbeat, go to the following line:

      ##    "response.time.statistics.90.percentile": "$monitor.getProcessingStatistics().getResponseTimePercentileMs(90.0, '###.##')":

      The ProcessingStatistics.getResponseTimePercentileMs(p, '###.##') function allows you to customize the percentiles displayed in the heartbeat endpoint response for the metrics ending in .<p>.percentile. Percentiles can be a helpful way to understand a metric’s distribution and identify patterns or trends over time. They can also be used to set performance targets or to identify bottlenecks in a system.

      In the context of server response metrics, you can use percentiles to compare a server’s response time to other servers or previous periods.

      You can use decimal values as described in the previous $monitor.getCpuLoad('###.##') table entry.

      To update the percentile, do one of the following.

      Choose from:

      • To change the percentile value, replace .90 with the desired percentile value:

        ##    "response.time.statistics.75.percentile": "$monitor.getProcessingStatistics().getResponseTimePercentileMs(75.0, '###.##')",

      • To specify a percentile in addition to the default 90th percentile, add a new line using the same format:

        "response.time.statistics.90.percentile": "$monitor.getProcessingStatistics().getResponseTimePercentileMs(90.0, '###.##')",
"response.time.statistics.50.percentile": "$monitor.getProcessingStatistics().getResponseTimePercentileMs(50.0, '###.##')",

        Example:

        Details

        Setting the value to 50 will display the 50th percentile of a server’s response time in the heartbeat endpoint response. A value of 200 milliseconds for the 50th percentile means that 50% of the server’s responses were faster than 200 milliseconds, while 50% were slower.

        Similarly, a value of 500 milliseconds for the 95th percentile means that 95% of the server’s responses were faster than 500 milliseconds, while 5% were slower.

    2. Save your changes.

  3. For a clustered PingAccess environment, repeat these steps on each node.