Skip to content

S
spring-boot
Commit e5295c01 authored by Phillip Webb's avatar Phillip Webb
Browse files
Options

Update HealthInformation reference documentation 

Clean and align with changes in Spring Boot 1.2

Fixes gh-2104
parent 71fd3b36
Hide whitespace changes
Inline Side-by-side
Showing with 85 additions and 25 deletions
spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
View file @ e5295c01
......@@ -86,8 +86,9 @@ The following endpoints are available:
|true
|`health`
|Shows application health information (defaulting to a simple '`OK`' message).
|false
|Shows full application health information when accessed securely or a simple '`status`'
message when accessed over an insecure HTTP connection.
|true
|`info`
|Displays arbitrary application info.
......@@ -137,13 +138,67 @@ that is being configured.
[[production-ready-health]]
=== Custom health information
The default information exposed by the `health` endpoint is a simple '`OK`' message. It
is often useful to perform some additional health checks, for example you might check
that a database connection works, or that a remote REST endpoint is functioning.
=== Health information
Health information can be used to check the status of your running application. It is
often used by monitoring software to alert someone if a production system goes down.
The default information exposed by the `health` endpoint depends on how it is accessed.
For an insecure unauthenticated connection a simple '`status`' message is returned, for a
secure or authenticated connection additional details are also displayed (see
<<production-ready-health-access-restrictions>> for HTTP details).
Heath information is collected from all
{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] beans defined
in your `ApplicationContext`. Spring Boot includes a number of auto-configured
`HealthIndicators` and you can also write your own.
=== Security with HealthIndicators
Information returned by `HealthIndicators` is often somewhat sensitive in nature. For
example and you probably don't want to publish details of your database server to the
world. For this reason, by default, only the health status is exposed on an insecure HTTP
connection. If you are happy for complete heath information to always be exposed you can
set `endpoints.health.sensitive` to `false`.
Heath responses are also cached to prevent "`denial of service`" attacks. Use the
`endpoints.health.time-to-live` property if you want to change the default cache period
of 1000 milliseconds.
==== Auto-configured HealthIndicators
The following `HealthIndicators` are auto-configured by Spring Boot when appropriate:
|===
|Name |Description
|{sc-spring-boot-actuator}/health/DiskSpaceHealthIndicator.{sc-ext}[`DiskSpaceHealthIndicator`]
|Checks for low disk space.
To provide custom health information you can register a Spring bean that implements the
|{sc-spring-boot-actuator}/health/DataSourceHealthIndicator.{sc-ext}[`DataSourceHealthIndicator`]
|Checks that a connection to `DataSource` can be obtained.
|{sc-spring-boot-actuator}/health/MongoHealthIndicator.{sc-ext}[`MongoHealthIndicator`]
|Checks that a Mongo database is up.
|{sc-spring-boot-actuator}/health/RabbitHealthIndicator.{sc-ext}[`RabbitHealthIndicator`]
|Checks that a Rabbit server is up.
|{sc-spring-boot-actuator}/health/SolrHealthIndicator.{sc-ext}[`RedisHealthIndicator`]
|Checks that a Redis server is up.
|{sc-spring-boot-actuator}/health/SolrHealthIndicator.{sc-ext}[`SolrHealthIndicator`]
|Checks that a Solr server is up.
|===
==== Writing custom HealthIndicators
To provide custom health information you can register Spring beans that implement the
{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] interface.
You need to provide an implementation of the `health()` method and return a `Health`
response. The `Health` response should include a status and can optionally include
additional details to be displayed.
[source,java,indent=0]
----
......@@ -155,30 +210,35 @@ To provide custom health information you can register a Spring bean that impleme
@Override
public Health health() {
// perform some specific health check
return ...
int errorCode = check(); // perform some specific health check
if (errorCode != 0) {
return Health.down().withDetail("Error Code", errorCode);
}
return Health.up();
}
}
----
Spring Boot provides a
{sc-spring-boot-actuator}/health/DataSourceHealthIndicator.{sc-ext}[`DataSourceHealthIndicator`]
implementation that attempts a simple database test (reusing the validation query set on the data
source, if any) as well as implementations for Redis, MongoDB and RabbitMQ. Spring Boot adds the
`HealthIndicator` instances automatically if beans of type `DataSource`, `MongoTemplate`,
`RedisConnectionFactory`, and `RabbitTemplate` respectively are present in the
`ApplicationContext`. A health indicator that checks free disk space is also provided.
In addition to Spring Boot's default {sc-spring-boot-actuator}/health/Status.{sc-ext}[`Status`]
types, it is also possible to introduce custom `Status` types to represent more
complex system states. In such cases a custom implementation of the
{sc-spring-boot-actuator}/health/HealthAggregator.{sc-ext}[`HealthAggregator`]
interface also needs to be provided, or the default implementation has to be configured
using the `management.health.status.order` configuration property.
For example, assuming a new `Status` with code `FATAL` is being used in one of your
`HealthIndicator` implementations. To configure the severity order add the following
to your application properties:
Besides implementing custom a `HealthIndicator` type and using out-of-box {sc-spring-boot-actuator}/health/Status.{sc-ext}[`Status`]
types, it is also possible to introduce custom `Status` types for different or more complex system
states. In that case a custom implementation of the {sc-spring-boot-actuator}/health/HealthAggregator.{sc-ext}[`HealthAggregator`]
interface needs to be provided or the default implementation has to be configured using the
`management.health.status.order` configuration property.
[source,properties,indent=0]
----
management.health.status.order: DOWN, OUT_OF_SERVICE, UNKNOWN, UP
----
Assuming a new `Status` with code `FATAL` is being used in one of your `HealthIndicator`
implementations. To configure the severity or order add the following to your application properties:
`management.health.status.order: DOWN, OUT_OF_SERVICE, UNKNOWN, UP`.
You might also want to register custom status mappings with the `HealthMvcEndpoint`
if you access the health endpoint over HTTP. For example you could map `FATAL` to
`HttpStatus.SERVICE_UNAVAILABLE`.
......@@ -411,7 +471,7 @@ If you don't want to expose endpoints over HTTP you can set the management port
[[production-ready-health-access-restrictions]]
=== Health endpoint anonymous access restrictions
=== HTTP Health endpoint access restrictions
The information exposed by the health endpoint varies depending on whether or not it's
accessed anonymously. By default, when accessed anonymously, any details about the
server's health are hidden and the endpoint will simply indicate whether or not the server
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment