Monitoring Instances

In certain deployments, such as Kubernetes, it can be useful to poll endpoints to check if an instance is running, and ready to handle requests. You can determine the status of an AM instance by using the following endpoints:

/json/health/live

Use the live endpoint to determine if AM instances are up and running.

If the instance is running the endpoint returns an HTTP status code of 200. If not, it returns a 503 response.

For example, use the following curl command to determine when an AM instance is alive: 

$ curl --include --retry 10 --retry-connrefused 'http://am.example.com:8080/am/json/health/live'
Warning: Transient problem: connection refused Will retry in 1 seconds. 10
Warning: retries left.
Warning: Transient problem: connection refused Will retry in 2 seconds. 9
Warning: retries left.
Warning: Transient problem: connection refused Will retry in 4 seconds. 8
Warning: retries left.
HTTP/1.1 200
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Cache-Control: private
Content-API-Version: resource=1.0
Content-Length: 0
Date: Mon, 09 Nov 2020 12:22:38 GMT
/json/health/ready

Use the ready endpoint to determine if AM instances are ready to process requests.

If the instance is ready to process requests, the endpoint returns an HTTP status code of 200. If not, it returns a 503 response.

One of the readiness checks the endpoint performs is that the CTS queue is not overloaded. The endpoint returns an HTTP 503 error if the following are both true:

  1. The CTS queue is more full than the configured threshold property (org.forgerock.services.cts.queue.readiness.threshold).

  2. The CTS data store is available.

A queue that is more full than the threshold, even though there is a CTS store available to process it, could indicate that the health of the AM instance is below expectations. That is why the endpoint returns HTTP 503.

The default threshold is 90% full, but you can configure the threshold percentage by using the org.forgerock.services.cts.queue.readiness.threshold advanced property. For more information, see "Advanced Properties".

For example, use the following curl command to determine when an AM instance is ready to process requests: 

$ curl --include --retry 10 --retry-connrefused 'http://am.example.com:8080/am/json/health/ready'
Warning: Transient problem: connection refused Will retry in 1 seconds. 10
Warning: retries left.
Warning: Transient problem: connection refused Will retry in 2 seconds. 9
Warning: retries left.
Warning: Transient problem: connection refused Will retry in 4 seconds. 8
Warning: retries left.
Warning: Transient problem: connection refused Will retry in 8 seconds. 7
Warning: retries left.
HTTP/1.1 200
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Cache-Control: private
Content-API-Version: resource=1.0
Content-Length: 0
Date: Mon, 09 Nov 2020 12:45:03 GMT

AM provides a deprecated isAlive.jsp page, to check whether AM is up. Point your application to the file under the deployment URL, such as https://openam.example.com:8443/openam/isAlive.jsp.

If you get a success code (with Server is ALIVE: in the body of the page returned), then the instance is in operation.

The isAlive.jsp page is deprecated and will be removed in a future version. Update your environment to use the live and ready endpoints instead.

Tip

The endpoints and isAlive.jsp page do not require any authentication. You may want to restrict access to them by the public, and instead only allow access from internal infrastructure.

For more advanced monitoring services that will let you monitor metrics, such as authentication and authorization outcomes, token-related operations, CTS queues, or JVM usage, see:

Read a different version of :