This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new e14584d camel-health - Update docs
e14584d is described below
commit e14584dc2fe4522081a1e0a97a0caffb37e68dbd
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Tue Jun 2 19:04:06 2020 +0200
camel-health - Update docs
---
.../modules/ROOT/pages/health-check.adoc | 107 +++++++++++++++++++--
1 file changed, 99 insertions(+), 8 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/health-check.adoc
b/docs/user-manual/modules/ROOT/pages/health-check.adoc
index 2c26a70..72e9f35 100644
--- a/docs/user-manual/modules/ROOT/pages/health-check.adoc
+++ b/docs/user-manual/modules/ROOT/pages/health-check.adoc
@@ -1,16 +1,102 @@
[[HealthCheck-HealthCheck]]
= Health Checks
-*Since Camel 2.20*
-
Camel provides support to probe the state of an integration via a pluggable
Health Check strategy based on the following concepts:
-- *HealthCheck:* represents a health check and defines its basic contract;
-- *HealthCheckResponse:* represents a health check invocation response;
-- *HealthCheckConfiguration:* a basic configuration object that holds some
basic settings like the minimum delay between calls, the number of times a
service may be reported as unhealthy before marking the check as failed;
besides these simple options, the check implementation is responsible for
implementing further limitations where needed;
-- *HealthCheckRegistry:* a registry for health checks;
-- *HealthCheckRepository:* a simple interface to define health check
providers. By default there is one that grabs all the checks available in the
registry so you can add your own check i.e. istantiating your bean in
spring/spring-boot; components can provide their own repository;
+- *HealthCheck:* represents a health check and defines its basic contract.
+- *HealthCheckResponse:* represents a health check invocation response.
+- *HealthCheckConfiguration:* a basic configuration object that holds some
basic settings like the minimum delay between calls, the number of times a
service may be reported as unhealthy before marking the check as failed;
besides these simple options, the check implementation is responsible for
implementing further limitations where needed.
+- *HealthCheckRegistry:* a registry for health checks. There is a single
default implementation and end users should really not implement their own.
+- *HealthCheckRepository:* a simple interface to define health check
providers. By default there is one that grabs all the checks available in the
registry so you can add your own check i.e. istantiating your bean in
spring/spring-boot; components can provide their own repository.
+
+== Health checks out of the box
+
+Camel provides three standard health checks out of the box
+
+- context - A `HealthCheck` which performs check whether the `CamelContext` is
started. This can be used for readiness checks; to know when Camel is fully
started and ready to handle traffic.
+- routes - A `HealthCheckRegistry` which discovers all the available routes in
`CamelContext` and checks whether they are all started.
+ This can be used for readiness checks; to know when Camel is fully started
and ready to handle traffic.
+ Combining with the supervised `RouteController` this allows to perform
readiness check for routes that are under supervising,
+ such as troublesome routes that may not startup the first time, and are
retried to be started in the background with backoff delays.
+- registry - A `HealthCheckRegistry` which discovers all the available custom
`HealthCheck` instances in the `Registry`.
+
+== IDs
+
+A `HealthCheck` and `HealthCheckRegistry` has an ID. The ID has the name
syntax `*name*-health-check`, or `*name*-health-check-repository`.
+With the prefix `-health-check` or `-health-check-repository`. When looking up
or resolving by IDs then the shorthand name can be used.
+
+For example `context-health-check` is the ID but can also be used by its
shorthand `context`.
+
+== Health Check configuration
+The `HealthCheckConfiguration` has the following options:
+
+[%header,cols=3*]
+|====
+| Name | Default | Description
+| enabled | true | Set if the check associated to this configuration is
enabled or not.
+| interval | | Set the check interval in milli seconds.
+| failureThreshold | | Set the number of failure before reporting the service
as un-healthy.
+|====
+
+The `interval` and `failureThreshold` are used for configuring health checks
to deal with flaky checks.
+For example assume you do not want to regard a check as immediately DOWN when
a check for the first time returns a response as DOWN.
+So you can specify the `interval=10000` and `failureThreshold=5`, which means
that the check has slacks, and will
+only report it as DOWN when there has been 5 failures in a row, with a minimum
of 10 second of interval between these checks.
+So in other words after minimum 50 seconds and 5 calls then it can be reported
as DOWN.
+
+== Configuring health-check
+
+Camel supports via `camel-main` to configure health-checks from configuration
files. This is possible for runtimes that leverage `camel-main`
+such as Camel on Spring Boot, or Camel K.
+
+Camel will automatic enable `context`, `routes` and `registry` health-checks
if `camel-health` is detected on the classpath.
+They are all enabled by default. However you can configure them, for example
to turn it off:
+
+[source,properties]
+----
+# global option to turn health-check off (will not install healt-check)
+### camel.health.enabled=false
+
+# allows to enable or disable health-checks from startup
+# for example to only use context health-check
+camel.health.context=true
+camel.health.registry=false
+camel.health.routes=false
+----
+
+== Configuring routes health-check
+
+The `routes` health check supports filtering by route id, or endpoint uri
using a pattern style (* as wildcard, and regexp supported).
+For example to turn off all routes that are from kafka, you can do:
+
+NOTE: Notice the syntax is a double map `[][]` to first index the health check
by id (eg `routes`), and then
+ the 2nd `[]` is the route id pattern. The double map `[][]` syntax is
also supported for custom health checks
+ that are of type `HealthCheckRepository`.
+
+[source,properties]
+----
+camel.health[routes][kafka*].enabled=false
+camel.health[routes][kafka*].failure-threshold=3
+----
+
+It's possible to set a default fallback configuration using `[*]` as the route
id:
+[source,properties]
+----
+camel.health[routes][kafka*].enabled=false
+camel.health[routes][kafka*].failure-threshold=3
+camel.health[routes][*].enabled=true
+camel.health[routes][*].failure-threshold=10
+----
+
+== JMX management
+
+The health check is managable via JMX (requires `camel-management` JAR on the
classpath).
+You can find the `DefaultHealthCheck` MBean under the `health` node in the
Camel JMX tree.
+
+This MBean allows at runtime to manage health-checks where you can enable and
disable checks based on their IDs.
+As well have the latest status whether the overall health check is healthy or
not.
+The MBean also allows invoking health checks based on IDs (or all of them).
== Writing a custom check:
@@ -21,7 +107,7 @@ There are a limited number of health checks provided by
Camel out of the box, so
public final class MyHealthCheck extends AbstractHealthCheck {
public MyHealthCheck() {
- super("camel", "my-check");
+ super("myapp", "my-check");
}
@Override
@@ -42,3 +128,8 @@ public final class MyHealthCheck extends AbstractHealthCheck
{
----
You can now make _MyHealthCheck_ available to camel by adding an instance to
the application context (Spring, Blueprint) or directly to the registry.
+The example `camel-example-main-health` has a custom health check.
+
+== Examples
+
+You can find a standalone example in the Camel examples in the
`camel-example-main-health` directory.
