HealthChecks

The RoadRunner Status Plugin provides a healthcheck status for various plugins such as http, grpc, temporal, jobs and centrifuge. This plugin provides an easy way to check the condition of the workers and ensure that they are ready to serve requests.

Activation of the Status Plugin

To activate the health/readiness checks endpoint, include a status section in your configuration file.

Here is an example:

.rr.yaml

version: "3"

status:
  address: 127.0.0.1:2114

The above configuration sets the address to 127.0.0.1:2114. This is the address that the plugin will listen to. You can change the address to any IP address and port number of your choice.

To access the health check, use the following URL: http://127.0.0.1:2114/health. This URL will return the health status of all plugins that are enabled and support health probes. To specify a particular plugin, you need to use the plugin query parameter: http://127.0.0.1:2114/health?plugin=http. In that case, the health status of the http plugin will be returned.

You can specify multiple plugins by separating them with a comma. For example, to check the health status of both the http and grpc plugins, you can use the following URL: http://127.0.0.1:2114/health?plugin=http&plugin=grpc.

The health check endpoint will return HTTP 200 if there is at least one worker ready to serve requests. If there are no workers ready to service requests, the endpoint will return HTTP 503 (or your unavailable status code, which can be set via configuration of the plugin). If there are any other errors, the endpoint will also return HTTP 503 (or your unavailable status code). The status plugin also returns a payload with a list of checked plugins and errors, if any, in the following format:

[
    {
        "plugin_name": "http",
        "error_message": "",
        "status_code": 200
    },
    {
        "plugin_name": "grpc",
        "error_message": "some error message",
        "status_code": 404
    }
]

Readiness Check

To access the readiness check, use the following URL: http://127.0.0.1:2114/ready.

The readiness check endpoint will return HTTP 200 if there is at least one worker ready to take the request (i.e., not currently busy with another request). If there is no worker ready or all workers are busy, the endpoint will return HTTP 503 status code (you can override this with the unavailable_status_code option).

Like the health check, you can target a specific plugin using the plugin query parameter:

• http://127.0.0.1:2114/ready?plugin=http

• http://127.0.0.1:2114/ready?plugin=grpc

You can specify multiple plugins by separating them with a comma. For example: http://127.0.0.1:2114/ready?plugin=http&plugin=grpc.

The response format is the same JSON structure as the /health endpoint.

Customizing the Not-Ready Status Code

By default, the Status Plugin uses a 503 status code. However, you can replace this status code with a custom one.

To achieve this, utilize the unavailable_status_code option:

.rr.yaml

version: "3"

status:
  address: 127.0.0.1:2114
  unavailable_status_code: 501

Check Timeout

The status plugin uses a timeout when checking the status of plugins. By default, this timeout is 60 seconds. You can customize it using the check_timeout option:

.rr.yaml

version: "3"

status:
  address: 127.0.0.1:2114
  check_timeout: 30s

Jobs plugin pipelines check

In addition to checking the health status of the workers, you can also examine the pipelines in the Jobs plugin using the following URL: http://127.0.0.1:2114/jobs

This URL will return the status of the pipelines in the Jobs plugin. The output will be in the following format:

plugin: jobs: pipeline: test-1 | priority: 13 | ready: true | queue: test-1 | active: 0 | delayed: 0 | reserved: 0 | driver: memory | error:  

Use cases

The health check endpoint serves the following purposes:

Kubernetes Readiness and Liveness Probes

In Kubernetes, you can use readiness and liveness probes to check the health of your application. It can be used as a readiness or liveness probe to ensure that your application is ready to serve requests. You can configure Kubernetes to check the health check endpoint and take appropriate action if the endpoint returns an error.

Read more here

AWS Target Group Health Checks

If you are using AWS Elastic Load Balancer, you can use it as a health check for your target group. You can configure the target group to check the health check endpoint and take appropriate action if the endpoint returns an error.

Read more here

GCE Load Balancing Health Checks

If you are using Google Cloud Platform, you can use it as a health check for your load balancer. You can configure the load balancer to check the health check endpoint and take appropriate action if the endpoint returns an error.

Read more here