Package ratpack.health

Class HealthCheckHandler

  • All Implemented Interfaces:
    Handler
    public class HealthCheckHandler
extends java.lang.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.registry.Registry;
 import ratpack.health.HealthCheck;
 import ratpack.health.HealthCheckHandler;
 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.Assert.*;

 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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_NAME_TOKEN
      The default path token name that indicates the individual health check to run.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getName()
      The name of the path token that may indicate a particular health check to execute.
      ratpack.exec.Throttle getThrottle()
      The throttle for executing health checks.
      void handle​(Context ctx)
      Renders health checks.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • HealthCheckHandler

        public HealthCheckHandler​(java.lang.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​(java.lang.String pathTokenName,
                             ratpack.exec.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 ratpack.exec.Throttle getThrottle()
        The throttle for executing health checks.
        Returns:
        the throttle for executing health checks.

      • getName

        public java.lang.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

      • handle

        public void handle​(Context ctx)
            throws java.lang.Exception
        Renders health checks.
        Specified by:
        handle in interface Handler
        Parameters:
        ctx - the request context
        Throws:
        java.lang.Exception - if anything goes wrong (exception will be implicitly passed to the context's Context.error(Throwable) method)