From 1fa1ed2b2805f731dcdf30327a5ff0b92ccf55e3 Mon Sep 17 00:00:00 2001 From: Luis Fernando Pollo Date: Thu, 23 Mar 2017 10:00:03 -0500 Subject: [PATCH 1/2] Document HTTP response format of health endpoint Add HTTP response format details for health endpoint, including default status codes and sample responses. See gh-8703 --- .../asciidoc/production-ready-features.adoc | 59 ++++++++++++++++++- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index ea346bc7e18..d92845c6b61 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -677,9 +677,8 @@ If you don't want to expose endpoints over HTTP you can set the management port ---- - [[production-ready-health-access-restrictions]] -=== HTTP health endpoint access restrictions +=== HTTP health endpoint format and access restrictions The information exposed by the health endpoint varies depending on whether or not it's accessed anonymously, and whether or not the enclosing application is secure. By default, when accessed anonymously in a secure application, any details about the @@ -689,6 +688,62 @@ endpoint being used in a denial of service attack. The `endpoints.health.time-to property is used to configure the caching period in milliseconds. It defaults to 1000, i.e. one second. +The HTTP status code in the response reflects the overall health status (e.g. “UP”=200, +“OUT_OF_SERVICE”=503, “DOWN”=503). The mappings can be changed by configuring +`endpoints.health.mapping.=XXX`. + +Sample summarized HTTP response (default for anonymous request): + +[source,indent=0] +---- +$ curl -i localhost:8080/health +HTTP/1.1 200 +X-Application-Context: application +Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8 +Content-Length: 15 + +{"status":"UP"} +---- + +Sample summarized HTTP response for status "DOWN" (notice the 503 status code): + +[source,indent=0] +---- +$ curl -i localhost:8080/health +HTTP/1.1 503 +X-Application-Context: application +Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8 +Content-Length: 17 + +{"status":"DOWN"} +---- + +Sample detailed HTTP response: + +[source,indent=0] +---- +$ curl -i localhost:8080/health +HTTP/1.1 200 OK +X-Application-Context: application +Content-Type: application/vnd.spring-boot.actuator.v1+json;charset=UTF-8 +Content-Length: 221 + +{ + "status" : "UP", + "diskSpace" : { + "status" : "UP", + "total" : 63251804160, + "free" : 31316164608, + "threshold" : 10485760 + }, + "db" : { + "status" : "UP", + "database" : "H2", + "hello" : 1 + } +} +---- + The above-described restrictions can be enhanced, thereby allowing only authenticated users full access to the health endpoint in a secure application. To do so, set `endpoints.health.sensitive` to `true`. Here's a summary of behavior (with default From fd53945fe06e744dae288503876aaf9c9d2c7745 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 10 Apr 2017 14:01:50 +0200 Subject: [PATCH 2/2] Polish "Document HTTP response format of health endpoint" Closes gh-8703 --- .../main/asciidoc/production-ready-features.adoc | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index d92845c6b61..ce307627836 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -382,9 +382,15 @@ 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`. +The HTTP status code in the response reflects the overall health status (e.g. `UP` +maps to 200, `OUT_OF_SERVICE` or `DOWN` to 503). You might also want to register custom +status mappings with the `HealthMvcEndpoint` if you access the health endpoint over HTTP. +For example, the following maps `FATAL` to `HttpStatus.SERVICE_UNAVAILABLE`: + +[source,properties,indent=0] +---- + endpoints.health.mappings.FATAL=503 +---- @@ -688,10 +694,6 @@ endpoint being used in a denial of service attack. The `endpoints.health.time-to property is used to configure the caching period in milliseconds. It defaults to 1000, i.e. one second. -The HTTP status code in the response reflects the overall health status (e.g. “UP”=200, -“OUT_OF_SERVICE”=503, “DOWN”=503). The mappings can be changed by configuring -`endpoints.health.mapping.=XXX`. - Sample summarized HTTP response (default for anonymous request): [source,indent=0]