Heartbeat endpoint

If the PingFederate server is running, the process of sending a request to the endpoint /pf/heartbeat.ping returns an HTTP 200 status. If the request times out or requires an extended amount of time to return, the server might be overloaded or experiencing other difficulties.

If a request requires more than two or three seconds to return, multiple factors in your PingFederate deployment might be responsible. We recommend that you develop a baseline for the desired response time by testing the heartbeat endpoint of your deployment at various times. This endpoint can be useful when load balancing a cluster of PingFederate instances. Some load balancers can alter the number of requests that are sent to a particular server based on the response code received, or the responsiveness of requests that are made to the heartbeat endpoint.

The output of the heartbeat endpoint can be modified to provide performance-related information, such as CPU and memory usage, and response times. The response metrics can help you make better auto-scaling decisions. The map size metrics can help you recognize performance issues.

The following example shows a report containing all the PingFederate server metrics available from the heartbeat endpoint.

{"items":[{
    "cpu.load": "77.31",
    "total.jvm.memory": "1045.955 MB",
    "free.jvm.memory": "486.56 MB",
    "used.jvm.memory": "559.395 MB",
    "total.physical.system.memory": "68.719 GB",
    "total.free.physical.system.memory": "15781.827 MB",
    "total.used.physical.system.memory": "52.938 GB",
    "number.of.cpus": "12",
    "response.statistics.count": "4074",
    "response.statistics.window.seconds": "10",
    "response.time.statistics.90.percentile": "450.883584",
    "response.time.statistics.mean": "112.82695139911635",
    "response.time.statistics.min": "0.0",
    "response.time.statistics.max": "7951.0",
    "response.concurrency.statistics.90.percentile": "49.2421875",
    "response.concurrency.statistics.mean": "45.562130177514796",
    "response.concurrency.statistics.min": "0.0",
    "response.concurrency.statistics.max": "51.0",
    "response.http.status.1xx": "0",
    "response.http.status.2xx": "3052",
    "response.http.status.3xx": "1017",
    "response.http.status.4xx": "0",
    "response.http.status.5xx": "0",
    "transaction.count": "2037",
    "transaction.errors": "0",
    "total.transactions": "4050",
    "total.failed.transactions": "0",
    "ds.JDBC.PFDefaultDS.request.count": "3945",
    "ds.JDBC.PFDefaultDS.response.time.90.percentile": "8.024064",
    "ds.JDBC.PFDefaultDS.response.time.mean": "2.2572877059569074",
    "ds.JDBC.PFDefaultDS.response.time.min": "0.0",
    "ds.JDBC.PFDefaultDS.response.time.max": "157.0",
    "engine.jetty.queued.thread.pool.utilized.threads": "52",
    "engine.jetty.queued.thread.pool.max.available.threads": "199",
    "engine.jetty.queued.thread.pool.utilization.rate": "0.2613065326633166",
    "engine.jetty.queued.thread.pool.queue.size": "0",
    "idp.session.registry.session.map.size": "2034",
    "sp.session.registry.session.map.size": "0",
    "session.state.attribute.map.size": "2034",
    "transaction.state.map.size": "0",
    "atm.default.token.map.size": "0"
}]}

The following table describes all the PingFederate server metrics available from the heartbeat endpoint.

Note: In the following table, for server metrics that end in .90.percentile, the current 90 value is determined by the ServerPercentilesList item in the com.pingidentity.monitoring.MonitoringService.xml file. 90 is the default value. For more information on how to edit this value, see step 4 in Liveliness and responsiveness.
Server metrics Description
cpu.load

Load on the PingFederate server's cores as a percentage of total capacity
total.jvm.memory

Total memory of the JVM
free.jvm.memory

Free memory of the JVM
used.jvm.memory

Used memory of the JVM
total.physical.system.memory

Total system memory
total.free.physical.system.memory

Free system memory
total.used.physical.system.memory

Used system memory
number.of.cpus

Number of cores on the PingFederate server
response.statistics.count

Number of items considered in the heartbeat report for the time and concurrency statistics
response.statistics.window.seconds

Time interval (in seconds) for the statistics report (this is an echo of the StatisticsWindowSecs parameter's value and provides context for the concurrency and time statistics)
response.time.statistics.90.percentile

The 90th percentile response time in milliseconds during the statistics window (for example, if this value is 168, then 90% of the report samples had response times below 168 milliseconds)
response.time.statistics.max

Longest time in milliseconds that the PingFederate server took to respond during the statistics window
response.time.statistics.mean

Mean time in milliseconds that the PingFederate server took to respond during the statistics window
response.time.statistics.min

Shortest time in milliseconds that the PingFederate server took to respond during the statistics window
response.concurrency.statistics.90.percentile

The 90th percentile response concurrency during the statistics window (for example, if this value is 124, then 90% of the report samples had response concurrency values below 124)
response.concurrency.statistics.max

Maximum number of HTTP requests that the PingFederate server processed concurrently during the statistics window
response.concurrency.statistics.mean

Mean number of HTTP requests that the PingFederate server processed concurrently during the statistics window
response.concurrency.statistics.min

Minimum number of HTTP requests that the PingFederate server processed concurrently during the statistics window
response.http.status.1xx

Number of 1xx HTTP response codes during the statistics window
response.http.status.2xx

Number of 2xx HTTP response codes during the statistics window
response.http.status.3xx

Number of 3xx HTTP response codes during the statistics window
response.http.status.4xx

Number of 4xx HTTP response codes during the statistics window
response.http.status.5xx

Number of 5xx HTTP response codes during the statistics window
transaction.count

Number of SSO, SLO, and STS transactions during the statistics window
transaction.errors

Number of failed SSO, SLO, and STS transactions during the statistics window
total.transactions

Total number of SSO, SLO, and STS transactions since the server started
total.failed.transactions

Total number of failed SSO, SLO, and STS transactions since the server started
ds.<type>.<id>.request.count

Number of requests for the data store during the statistics window
ds.<type>.<id>.response.time.90.percentile

The data store's 90th percentile response time in milliseconds during the statistics window
ds.<type>.<id>.response.time.mean

The data store's mean response time in milliseconds during the statistics window
ds.<type>.<id>.response.time.min

The data store's minimum response time in milliseconds during the statistics window
ds.<type>.<id>.response.time.max

The data store's maximum response time in milliseconds during the statistics window
<admin|engine>.jetty.queued.thread.pool.utilized.threads

Number of threads in the Jetty thread pool that are currently in use
<admin|engine>.jetty.queued.thread.pool.max.available.threads

Maximum number of threads in the Jetty thread pool
<admin|engine>.jetty.queued.thread.pool.utilization.rate

The threads in the pool that are currently in use, as a fraction of the maximum available threads
<admin|engine>.jetty.queued.thread.pool.queue.size

Number of requests currently queued waiting to be handled by a thread in the pool
idp.session.registry.session.map.size

Number of identity provider sessions
sp.session.registry.session.map.size

Number of service provider sessions
session.state.attribute.map.size

Number of items in the session state attribute map
transaction.state.map.size

Number of items in the SSO transaction state map
atm.<atm>.token.map.size

Number of tokens in the access token manager with the ID specified by <atm>

As indicated in the table, the values of some metrics are calculated over a configurable time window. The default statistics window is five minutes.

To customize the statistics window period, change the value of the StatisticsWindowSecs parameter in the <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.monitoring.MonitoringService.xml file. This file also lets you specify additional JMX MBean attributes that will be made available to the heartbeat page templates.

For more information, see Customizing the heartbeat message

Response-time logging

By default, the audit logs record the processing time for each transaction. With audit logging enabled, you can identify the speed with which PingFederate processes the following transaction types:

  • Single sign-on (SSO)
  • OAuth
  • Security token services (STS)

Depending on your logging configuration, audit logging might not log any transactions. For more information, see Security audit logging.

The following provides examples of the default audit log.
2019-11-10 13:24:57,493| tid:cYunBsgybiw_fiRnJjkAhbIXvzc| AUTHN_SESSION_USED| | 127.0.0.1 | | ac_client| | localhost| IdP| success| PdFormAdpt| | 17
2019-11-10 13:24:58,720| tid:cYunBsgybiw_fiRnJjkAhbIXvzc| OAuth| 5c60f022-1e9d-3fbe-9749-4b9ca5591356| 127.0.0.1 | | ac_client| OAuth20| localhost| AS| success| PdFormAdpt| | 7

Processing times are shown at the end of the entry in milliseconds.