PingOne

LDAP gateway health endpoints

To monitor the health of a running Lightweight Directory Access Protocol (LDAP) gateway client, you can configure the gateway client to expose HTTP endpoints that return metrics indicating the health of the application.

Enable the probes for an LDAP gateway client running in a Docker container.

Before you begin

Make sure:

  • You added an LDAP gateway and are ready to start the gateway instance in a Docker container.

  • If you have a valid gateway credential, have it ready. Alternatively, you can create a new credential on the Overview tab in the gateway details. Learn more in Creating or revoking a gateway credential.

  • Docker is installed and the Docker Engine is running.

Steps

  1. Start the gateway instance in a Docker container and add the following parameter to the Docker command:

    -e SPRING_PROFILES_ACTIVE=enableProbes

  2. At a command prompt, run the Docker command.

URL and port

The LDAP gateway client exposes the following HTTP endpoints on port 8080 inside the Docker container. These endpoints are included in the default SpringBoot health endpoints. Learn more about SpringBoot health endpoints in the Spring documentation.

  • /actuator/health

  • /actuator/health/ldap

  • /actuator/health/pingOne

Response body

When a GET request is made to the /actuator/health endpoint, the application responds with a JSON object detailing the overall status and the status of various components, including the LDAP gateway and PingOne described below:

  • "status": "UP": Indicates all components are healthy.

  • "status": "DOWN": Indicates at least one component is unhealthy.

To get the status of a specific component, add the component’s name to the URL.

Health metrics

The gateway client tracks metrics about the LDAP connection pools. Use these values to monitor the connection pool behavior.

Connection attempt counters

The following metrics track how many times the gateway tried to open a new connection to the LDAP directory server:

Property Description

numberOfSuccessfulConnectionAttemptsForGenericPool

Number of connections successfully opened to the LDAP server for the generic pool since pool creation.

numberOfSuccessfulConnectionAttemptsForBindPool

Number of connections successfully opened to the LDAP server for the bind pool since pool creation.

numberOfFailedConnectionAttemptsForGenericPool

Number of attempts that failed to open a connection for the generic pool since pool creation.

numberOfFailedConnectionAttemptsForBindPool

Number of attempts that failed to open a connection for the bind pool since the pool creation.

Closed connection counters

The following metrics track why the gateway removed connections from a pool:

Property Description

numberOfConnectionsClosedDefunctInGenericPool

Number of general connections closed because they stopped working (for example, after a failed operation or a missed background health check).

numberOfConnectionsClosedDefunctInBindPool

Number of login connections closed because they stopped working (for example, after a failed operation or a missed background health check).

numberOfConnectionsClosedExpiredInGenericPool

Number of general connections closed because they reached their maximum lifetime.

numberOfConnectionsClosedExpiredInBindPool

Number of login connections closed because they reached their maximum lifetime.

numberOfConnectionsClosedUnneededInGenericPool

Number of general connections closed because the pool held more connections than needed, shrinking the pool during periods of lower traffic.

numberOfConnectionsClosedUnneededInBindPool

Number of login connections closed because the pool held more connections than needed, shrinking the pool during periods of lower traffic.

Checkout counters

The following metrics track how the gateway obtained connections from the pool:

Property Description

numberOfSuccessfulCheckoutsFromGenericPool

Number of times the gateway successfully checked out a connection from the general pool to run a directory task.

numberOfSuccessfulCheckoutsFromBindPool

Number of times the gateway successfully checked out a connection from the login pool to perform a password check.

numberOfSuccessfulCheckoutsWithoutWaitingFromGenericPool

Number of times the gateway checked out a connection from the general pool without waiting.

numberOfSuccessfulCheckoutsWithoutWaitingFromBindPool

Number of times the gateway checked out a connection from the login pool without waiting.

numberOfSuccessfulCheckoutsAfterWaitingFromGenericPool

Number of times a request waited to check out a general connection from the pool.

numberOfSuccessfulCheckoutsAfterWaitingFromBindPool

Number of times a request waited to check out a connection from the login pool.

numberOfSuccessfulCheckoutsNewConnectionFromGenericPool

Number of times the gateway handled a general connection request by opening a new connection instead of reusing an existing one.

numberOfSuccessfulCheckoutsNewConnectionFromBindPool

Number of times the gateway handled a general connection request by opening a new connection instead of reusing an existing one.

numberOfFailedCheckoutsFromGenericPool

Number of times a request waited to check out a general connection from the pool

numberOfFailedCheckoutsFromBindPool

Number of times a request to get a request waited to check out a connection from the login pool.

numberOfReleasedValidConnectionsToGenericPool

Number of connections returned to the general pool in a healthy, working state after a directory task finished.

numberOfReleasedValidConnectionsToBindPool

Number of connections returned to the login pool in a healthy, working state after a password check.

LDAP server connection status

When a GET request is made to the /actuator/health/ldap endpoint, the following JSON object is returned when the gateway client is connected to the LDAP server:

 {
    "status": "UP",
    "details": {
      "numberOfActiveConnectionsInGenericPool": 1,
      "spaceLeftInGenericPool": 99,
      "maximumPossibleConnectionsInGenericPool": 100,
      "numberOfActiveConnectionsInBindPool": 1,
      "spaceLeftInBindPool": 99,
      "maximumPossibleConnectionsInBindPool": 100
   }
 }

The following statuses are returned:

  • "status": "UP": Indicates the gateway client is connected to the LDAP server.

  • "status": "DOWN": Indicates the gateway client isn’t connected to the LDAP server.

The following table provides more information on the status of the connection pools the gateway client manages:

Property Description

maximumPossibleConnectionsInGenericPool

Maximum possible connections allowed in the generic connection pool.

numberOfActiveConnectionsInGenericPool

The number of active connections in use by the gateway client to handle LDAP requests.

spaceLeftInGenericPool

The number of available connections left in the generic pool.

maximumPossibleConnectionsInBindPool

Maximum possible connections allowed in the bind connection pool.

numberOfActiveConnectionsInBindPool

The number of active connections in use by the gateway client to handle LDAP bind requests.

spaceLeftInBindPool

The number of available connections left in the bind pool.

PingOne connection status

When a GET request is made to the /actuator/health/pingOne endpoint, the following JSON object is returned when the gateway client is connected to PingOne:

 {
   "status": "UP",
   "details": {
   "numberOfActiveConnections": 4
   }
 }

The following statuses are returned:

  • "status": "UP": Indicates the gateway client has at least one active WebSocket connection to PingOne.

  • "status": "DOWN": Indicates the gateway client doesn’t have any active WebSocket connections to PingOne.

The following table provides more information on the gateway client’s connection status to PingOne:

Property Description

numberOfActiveConnections

The number of active WebSocket connections to PingOne.

The gateway client maintains WebSocket connections to each available site in the PingOne environment’s geography.

For example:

  • us-east

  • us-west

The gateway client should always have at least one active connection to be considered healthy.