From 00099552dbea50d3a25664a80e77429c322cd0ef Mon Sep 17 00:00:00 2001 From: Ben Hale Date: Mon, 14 Nov 2016 15:32:43 -0800 Subject: [PATCH] Add Logger actuator documentation Add Actuator and Reference documentation for the `/logger` endpoint. This documentation includes information on listing, reading, and modifying the configuration of loggers. Closes gh-7390 See gh-7086 --- .../src/main/asciidoc/loggers.adoc | 61 +++++++++++++++++++ .../hypermedia/EndpointDocumentation.java | 18 ++++++ .../asciidoc/production-ready-features.adoc | 37 +++++++++++ 3 files changed, 116 insertions(+) create mode 100644 spring-boot-actuator-docs/src/main/asciidoc/loggers.adoc diff --git a/spring-boot-actuator-docs/src/main/asciidoc/loggers.adoc b/spring-boot-actuator-docs/src/main/asciidoc/loggers.adoc new file mode 100644 index 0000000000..735fec1104 --- /dev/null +++ b/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[] diff --git a/spring-boot-actuator-docs/src/restdoc/java/org/springframework/boot/actuate/hypermedia/EndpointDocumentation.java b/spring-boot-actuator-docs/src/restdoc/java/org/springframework/boot/actuate/hypermedia/EndpointDocumentation.java index 79a931a302..4f933ef598 100644 --- a/spring-boot-actuator-docs/src/restdoc/java/org/springframework/boot/actuate/hypermedia/EndpointDocumentation.java +++ b/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"); 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 8f2c11e704..1a78e186db 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/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.