Merge pull request #7390 from nebhale/logger-actuator-docs

* pr/7390:
  Add Logger actuator documentation

spring-boot-actuator-docs/src/main/asciidoc/loggers.adoc

@@ -0,0 +1,61 @@
+=== /loggers
+This endpoint allows you to view and modify the log levels for the loggers in your
+application.  It builds on top of the `LoggingSystem` abstraction and supports the same
+logging frameworks.  The logging levels are defined by the `LogLevel` enumeration and
+consists of the following values (although not all logging systems support the full set):
+
+* `TRACE`
+* `DEBUG`
+* `INFO`
+* `WARN`
+* `ERROR`
+* `FATAL`
+* `OFF`
+* `null`
+
+The `configuredLevel` property reflects an explicitly configured logger level, while the
+`effectiveLevel` property reflects the logger level inherited from parent loggers. The
+`effectiveLevel` is managed by each logging framework and reflects the propagation rules
+inherent to and configured in that framework.  `null` indicates that there is no explicit
+configuration defined.
+
+
+
+==== Listing All Loggers
+Example curl request:
+include::{generated}/loggers/curl-request.adoc[]
+
+Example HTTP request: [small]##link:../health[icon:external-link[role="silver"]]##
+include::{generated}/loggers/http-request.adoc[]
+
+Example HTTP response:
+include::{generated}/loggers/http-response.adoc[]
+
+
+
+==== Getting a Single Logger
+Example curl request:
+include::{generated}/single-logger/curl-request.adoc[]
+
+Example HTTP request: [small]##link:../health[icon:external-link[role="silver"]]##
+include::{generated}/single-logger/http-request.adoc[]
+
+Example HTTP response:
+include::{generated}/single-logger/http-response.adoc[]
+
+
+
+==== Configuring a Logger
+Setting the `configuredLevel` of a logger requires `POSTing` a partial payload to the
+resource. The `configuredLevel` property must contain a string representation of the
+enumeration described above.  `null` indicates that the log level should be unset,
+allowing it to inherit configuration from it's parent.
+
+Example curl request:
+include::{generated}/set-logger/curl-request.adoc[]
+
+Example HTTP request: [small]##link:../health[icon:external-link[role="silver"]]##
+include::{generated}/set-logger/http-request.adoc[]
+
+Example HTTP response:
+include::{generated}/set-logger/http-response.adoc[]

spring-boot-actuator-docs/src/restdoc/java/org/springframework/boot/actuate/hypermedia/EndpointDocumentation.java

@@ -58,6 +58,7 @@ import org.springframework.util.StringUtils;
 
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 @RunWith(SpringRunner.class)
@@ -108,6 +109,23 @@ public class EndpointDocumentation {
 				.andDo(document("partial-logfile"));
 	}
 
+	@Test
+	public void singleLogger() throws Exception {
+		this.mockMvc
+				.perform(get("/loggers/org.springframework.boot")
+						.accept(MediaType.APPLICATION_JSON))
+				.andExpect(status().isOk()).andDo(document("single-logger"));
+	}
+
+	@Test
+	public void setLogger() throws Exception {
+		this.mockMvc
+				.perform(post("/loggers/org.springframework.boot")
+						.contentType(MediaType.APPLICATION_JSON)
+						.content("{\"configuredLevel\": \"DEBUG\"}"))
+				.andExpect(status().isOk()).andDo(document("set-logger"));
+	}
+
 	@Test
 	public void endpoints() throws Exception {
 		final File docs = new File("src/main/asciidoc");

spring-boot-docs/src/main/asciidoc/production-ready-features.adoc

@@ -108,6 +108,10 @@ authenticated).
 |Displays arbitrary application info.
 |false
 
+|`loggers`
+|Shows and modifies the configuration of loggers in the application.
+|true
+
 |`liquibase`
 |Shows any Liquibase database migrations that have been applied.
 |true
@@ -945,6 +949,39 @@ documentation].
 
 
 
+[[production-ready-loggers]]
+== Loggers
+Spring Boot Actuator includes the ability to view and configure the log levels of your
+application at runtime.  You can view either the entire list or an individual logger's
+configuration which is made up of both the explictily configured logging level as well as
+the effective logging level given to it by the logging framework.  These levels can be:
+
+* `TRACE`
+* `DEBUG`
+* `INFO`
+* `WARN`
+* `ERROR`
+* `FATAL`
+* `OFF`
+* `null`
+
+with `null` indicating that there is no explict configuration.
+
+
+
+[[production-ready-logger-configuration]]
+=== Configure a Logger
+In order to configure a given logger, you `POST` a partial entity to the resource's URI:
+
+[source,json,indent=0]
+----
+	{
+		"configuredLevel": "DEBUG"
+	}
+----
+
+
+
 [[production-ready-metrics]]
 == Metrics
 Spring Boot Actuator includes a metrics service with '`gauge`' and '`counter`' support.