Package ratpack.core.health

Class HealthCheckHandler

  • All Implemented Interfaces:
    Handler
    public class HealthCheckHandler
extends Object
implements Handler
    A handler that executes health checks and renders the results.

    The handler obtains health checks via the context's registry. Typically, health checks are added to the server registry. 

    
 import ratpack.exec.Promise;
 import ratpack.exec.registry.Registry;
 import ratpack.core.health.HealthCheck;
 import ratpack.core.health.HealthCheckHandler;
 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.jupiter.api.Assertions.*;

 public class Example {

   static class ExampleHealthCheck implements HealthCheck {
     public String getName() {
       return "example"; // must be unique within the application
     }

     public Promise<HealthCheck.Result> check(Registry registry) throws Exception {
       return Promise.value(HealthCheck.Result.healthy());
     }
   }

   public static void main(String... args) throws Exception {
     EmbeddedApp.of(s -> s
       .registryOf(r -> r
         .add(new ExampleHealthCheck())
         .add(HealthCheck.of("inline", registry -> // alternative way to implement health checks
           Promise.value(HealthCheck.Result.unhealthy("FAILED"))
         ))
       )
       .handlers(c -> c
         .get("health/:name?", new HealthCheckHandler())
       )
     ).test(httpClient -> {
       // Run all health checks
       String result = httpClient.getText("health");
       String[] results = result.split("\n");
       assertEquals(2, results.length);
       assertEquals("example : HEALTHY", results[0]);
       assertEquals("inline : UNHEALTHY [FAILED]", results[1]);

       // Run a single health check
       result = httpClient.getText("health/example");
       assertEquals("example : HEALTHY", result);
     });
   }
 }

    The output format

    The handler creates a HealthCheckResults object with the results of running the health checks and renders it. Ratpack provides a default renderer for HealthCheckResults objects, that renders results as plain text one per line with the format: 

    name : HEALTHY|UNHEALTHY [message] [exception]

    If any result is unhealthy, a 503 status will be emitted, else 200.

    To change the output format, simply add your own renderer for this type to the registry.

    Concurrency

    The concurrency of the health check execution is managed by a Throttle. By default, an unlimited throttle is used. A sized throttle can be explicitly given to the constructor.

    Rendering single health checks

    The handler checks for the presence of a path token to indicate the name of an individual check to execute. By default, the token is named "name". If a path token is present, but indicates the name of a non-existent health check, a 404 client error will be raised.

    See Also:
    HealthCheck, HealthCheckResults

    • Constructor Detail

      • HealthCheckHandler

        public HealthCheckHandler​(String pathTokenName)
        Uses an unlimited throttle and the given name for the health check identifying path token.
        Parameters:
        pathTokenName - health check name
        See Also:
        HealthCheckHandler(String, Throttle)

      • HealthCheckHandler

        protected HealthCheckHandler​(String pathTokenName,
                             Throttle throttle)
        Constructor.

        The path token name parameter specifies the name of the path token that, if present, indicates the single health check to execute. If this path token is not present, all checks will be run.

        The throttle controls the concurrency of health check execution. The actual parallelism of the health check executions is ultimately determined by the size of the application event loop in conjunction with the throttle size. Generally, an unlimited throttle is appropriate unless there are many health checks that are executed frequently as this may degrade the performance of other requests. To serialize health check execution, use a throttle of size 1.

        Parameters:
        pathTokenName - the name of health check
        throttle - the throttle for health check execution

    • Method Detail

      • getThrottle

        public Throttle getThrottle()
        The throttle for executing health checks.
        Returns:
        the throttle for executing health checks.

      • getName

        public String getName()
        The name of the path token that may indicate a particular health check to execute.
        Returns:
        the name of the path token that may indicate a particular health check to execute