Status Endpoint#

The Curity Identity Server contains an HTTP endpoint providing node status information. Its operation is configured by the following environment variables.

By default, this status endpoint is enabled, however it can be disabled by setting the STATUS_CMD_ENABLED environment variable to false or by starting idsvr with the --no-status parameter.

The status endpoint supports HTTP GET and HEAD requests to the / path. The response will have status code:

• 200 if the node is started and configured. Note that a 200 status code means the node is configured but doesn’t ensure the server is listening for functional requests. For instance, the node may have a service role that is disabled or the internal HTTP server may still be starting/reconfiguring. To know if a node is ready to serve functional requests use the isServing JSON field or the /serving request path (see below).
• 503 if the node is not started or not yet configured.

In both cases, the response body will contain a JSON representation of the node status, containing the following fields:

• isReady

  • false - the node is not ready to process requests (e.g. it is still booting or is shutting down).
  • true - the node is ready to receive and process requests (but may be disconnected from the admin).

• nodeState

  • BOOTING - the node is starting up and not ready to process requests.
  • WAITING - the node is ready to process requests with the latest configuration that is has; however, it is still waiting to connect to the admin, so configuration may be stale.
  • RUNNING - the node is ready to process requests and is connected to the admin node.
  • ERROR - the node is in an unrecoverable error state.
  • STOPPING - the node is shutting down and not able to process requests.

• clusterState
  • STANDALONE - the node has clustering disabled.
  • CONNECTING_TO_CLUSTER - the node is not an admin node and is trying to connect (for the first time) or reconnect to the admin node.
  • CONNECTED - the node is not admin and is connected to the admin node.
  • ADMIN - the node is an admin node.
  • ERROR - an unexpected error occurred when checking the cluster state.

• configurationState
  • UNINITIALIZED - the node is not configured and therefore unable to correctly process requests.
  • CONFIGURED - the node is fully configured.
  • RECONFIGURING - the node is currently consuming a new configuration. A previous configuration is still valid and will be used in the meanwhile for any request processing.

• transactionId - an opaque string identifier for the last committed transaction seen by the current node.

• isServing

  • false - the node’s HTTP server that serves the runtime endpoints is not running.
  • true - the node’s HTTP server that serves the runtime endpoints is running.

• isAdminServing (this field is returned only on admin nodes)

  • false - the node’s HTTP server that serves the admin endpoints (i.e. an endpoint serving Admin UI requests) is not running.
  • true - the node’s HTTP server that serves the admin endpoints is running.

• pluginsInitialized

  • true - all the plugins installed in the node are done initializing.
  • false - some plugins installed in the node are still initializing.

• serviceRole - the service-role of the current node.

• threadPool - statistics about the HTTP Server’s Thread Pool.

  • busy - number of busy threads.
  • ready - number of ready threads.
  • leased - number of leased threads.
  • idle - number of idle threads.
  • min - configured minimum number of threads.
  • max - configured minimum number of threads.
  • utilizationRate - thread utilization rate. May include background jobs, not only HTTP requests.
  • state - one of STOPPED, STARTING, STARTED, STOPPING, FAILED.

• httpRequests - statistics about HTTP Requests.

  • running - number of HTTP Requests currently being handled (as counted by the root HTTP request handler).
  • utilizationRate - running / threadPool.max. Includes only HTTP requests.

The status endpoint also contains the /serving and /admin-serving paths to expose the isServing and isAdminServing information respectively via the status code, which is useful if the probing system is unable to process JSON representations. These paths accept both GET and HEAD requests. The response for the /serving path will have an empty body and status code:

• 200 - the node’s HTTP server that serves the runtime endpoints is running.
• 503 - the node’s HTTP server that serves the runtime endpoints is not running.

The response for the /admin-serving path will have an empty body and status code:

• 200 - the node’s HTTP server that serves the admin endpoints is running.
• 503 - the node’s HTTP server that serves the admin endpoints is not running.
• 404 - the node is not admin.

Note that the /admin-serving path is only served on admin nodes. On runtime nodes, a request to this path will return 404.

Command line tool#

The Curity Identity Server installation also contains the bin/status command line tool that can be used to probe the HTTP status endpoint. It uses the same environment variables the server uses and has two invocation parameters:

• -j or --json - if present, the response written to the standard output is in the JSON format; otherwise it is written in plain text.
• -h or --help - prints the synopsis of the tool
• -v - not used but maintained for backward compatibility reasons

The status tool performs a request to the local node status endpoint and writes the response body to the standard output. The tool exit code is described in the following table.