public class HealthCheckHandler extends Object implements Handler
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.ExecControl;
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(ExecControl execControl, Registry registry) throws Exception {
return execControl.promiseOf(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", (execControl, registry) -> // alternative way to implement health checks
execControl.promiseOf(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 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]
To change the output format, simply add your own renderer for this type to the registry.
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.
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.
HealthCheck
,
HealthCheckResults
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_NAME_TOKEN
The default path token name that indicates the individual health check to run.
|
Modifier | Constructor and Description |
---|---|
|
HealthCheckHandler()
Uses the default values of
DEFAULT_NAME_TOKEN and an unlimited throttle. |
|
HealthCheckHandler(String pathTokenName)
Uses an unlimited throttle and the given name for the health check identifying path token.
|
protected |
HealthCheckHandler(String pathTokenName,
Throttle throttle)
Constructor.
|
|
HealthCheckHandler(Throttle throttle)
Uses the
DEFAULT_NAME_TOKEN and the given throttle. |
Modifier and Type | Method and Description |
---|---|
String |
getName()
The name of the path token that may indicate a particular health check to execute.
|
Throttle |
getThrottle()
The throttle for executing health checks.
|
void |
handle(Context ctx)
Renders health checks.
|
public static final String DEFAULT_NAME_TOKEN
public HealthCheckHandler()
DEFAULT_NAME_TOKEN
and an unlimited throttle.HealthCheckHandler(String, Throttle)
public HealthCheckHandler(String pathTokenName)
pathTokenName
- health check nameHealthCheckHandler(String, Throttle)
public HealthCheckHandler(Throttle throttle)
DEFAULT_NAME_TOKEN
and the given throttle.throttle
- the throttle for health check executionHealthCheckHandler(String, Throttle)
protected HealthCheckHandler(String pathTokenName, Throttle throttle)
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.
pathTokenName
- the name of health checkthrottle
- the throttle for health check executionpublic Throttle getThrottle()
public String getName()