Merge pull request #17515 from htztomic

* pr/17515:
  Polish "Add support for configuring logging groups"
  Add support for configuring logging groups via endpoint

Closes gh-17515

Author: mbhave

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/asciidoc/endpoints/loggers.adoc

@@ -57,6 +57,21 @@ include::{snippets}loggers/single/response-fields.adoc[]
 
 
 
+[[loggers-group]]
+== Retrieving a Single Group
+
+To retrieve a single group, make a `GET` request to `/actuator/loggers/{group.name}`,
+as shown in the following curl-based example:
+
+include::{snippets}loggers/group/curl-request.adoc[]
+
+The preceding example retrieves information about the logger group named `test`. The
+resulting response is similar to the following:
+
+include::{snippets}loggers/group/http-response.adoc[]
+
+
+
 [[loggers-setting-level]]
 == Setting a Log Level
 
@@ -81,6 +96,30 @@ include::{snippets}loggers/set/request-fields.adoc[]
 
 
 
+[[loggers-setting-level]]
+== Setting a Log Level for a Group
+
+To set the level of a logger, make a `POST` request to
+`/actuator/loggers/{group.name}` with a JSON body that specifies the configured level
+for the logger group, as shown in the following curl-based example:
+
+include::{snippets}loggers/setGroup/curl-request.adoc[]
+
+The preceding example sets the `configuredLevel` of the `test` logger group to `DEBUG`.
+
+
+
+[[loggers-setting-level-request-structure]]
+=== Request Structure
+
+The request specifies the desired level of the logger group. The following table describes the
+structure of the request:
+
+[cols="3,1,3"]
+include::{snippets}loggers/set/request-fields.adoc[]
+
+
+
 [[loggers-clearing-level]]
 == Clearing a Log Level
 

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/logging/LoggersEndpointAutoConfiguration.java

@@ -16,6 +16,7 @@
 
 package org.springframework.boot.actuate.autoconfigure.logging;
 
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.boot.actuate.autoconfigure.endpoint.condition.ConditionalOnAvailableEndpoint;
 import org.springframework.boot.actuate.logging.LoggersEndpoint;
 import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
@@ -24,6 +25,7 @@
 import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
 import org.springframework.boot.autoconfigure.condition.SpringBootCondition;
+import org.springframework.boot.logging.LoggerGroups;
 import org.springframework.boot.logging.LoggingSystem;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.ConditionContext;
@@ -45,8 +47,9 @@ public class LoggersEndpointAutoConfiguration {
 	@ConditionalOnBean(LoggingSystem.class)
 	@Conditional(OnEnabledLoggingSystemCondition.class)
 	@ConditionalOnMissingBean
-	public LoggersEndpoint loggersEndpoint(LoggingSystem loggingSystem) {
-		return new LoggersEndpoint(loggingSystem);
+	public LoggersEndpoint loggersEndpoint(LoggingSystem loggingSystem,
+			ObjectProvider<LoggerGroups> springBootLoggerGroups) {
+		return new LoggersEndpoint(loggingSystem, springBootLoggerGroups.getIfAvailable(LoggerGroups::new));
 	}
 
 	static class OnEnabledLoggingSystemCondition extends SpringBootCondition {

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/documentation/LoggersEndpointDocumentationTests.java

@@ -17,14 +17,18 @@
 package org.springframework.boot.actuate.autoconfigure.endpoint.web.documentation;
 
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.EnumSet;
 import java.util.List;
+import java.util.Map;
 
 import org.junit.jupiter.api.Test;
 
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.actuate.logging.LoggersEndpoint;
 import org.springframework.boot.logging.LogLevel;
 import org.springframework.boot.logging.LoggerConfiguration;
+import org.springframework.boot.logging.LoggerGroups;
 import org.springframework.boot.logging.LoggingSystem;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.context.annotation.Bean;
@@ -54,9 +58,21 @@ class LoggersEndpointDocumentationTests extends MockMvcEndpointDocumentationTest
 			fieldWithPath("configuredLevel").description("Configured level of the logger, if any.").optional(),
 			fieldWithPath("effectiveLevel").description("Effective level of the logger."));
 
+	private static final List<FieldDescriptor> groupLevelFields;
+
+	static {
+		groupLevelFields = Arrays.asList(
+				fieldWithPath("configuredLevel").description("Configured level of the logger group")
+						.type(LogLevel.class).optional(),
+				fieldWithPath("members").description("Loggers that are part of this group").optional());
+	}
+
 	@MockBean
 	private LoggingSystem loggingSystem;
 
+	@Autowired
+	private LoggerGroups loggerGroups;
+
 	@Test
 	void allLoggers() throws Exception {
 		given(this.loggingSystem.getSupportedLogLevels()).willReturn(EnumSet.allOf(LogLevel.class));
@@ -66,8 +82,10 @@ void allLoggers() throws Exception {
 		this.mockMvc.perform(get("/actuator/loggers")).andExpect(status().isOk())
 				.andDo(MockMvcRestDocumentation.document("loggers/all",
 						responseFields(fieldWithPath("levels").description("Levels support by the logging system."),
-								fieldWithPath("loggers").description("Loggers keyed by name."))
-										.andWithPrefix("loggers.*.", levelFields)));
+								fieldWithPath("loggers").description("Loggers keyed by name."),
+								fieldWithPath("groups").description("Logger groups keyed by name"))
+										.andWithPrefix("loggers.*.", levelFields)
+										.andWithPrefix("groups.*.", groupLevelFields)));
 	}
 
 	@Test
@@ -78,6 +96,12 @@ void logger() throws Exception {
 				.andDo(MockMvcRestDocumentation.document("loggers/single", responseFields(levelFields)));
 	}
 
+	@Test
+	void loggerGroups() throws Exception {
+		this.mockMvc.perform(get("/actuator/loggers/test")).andExpect(status().isOk())
+				.andDo(MockMvcRestDocumentation.document("loggers/group", responseFields(groupLevelFields)));
+	}
+
 	@Test
 	void setLogLevel() throws Exception {
 		this.mockMvc
@@ -89,6 +113,26 @@ void setLogLevel() throws Exception {
 		verify(this.loggingSystem).setLogLevel("com.example", LogLevel.DEBUG);
 	}
 
+	@Test
+	void setLogLevelOfLoggerGroup() throws Exception {
+		this.mockMvc
+				.perform(post("/actuator/loggers/test")
+						.content("{\"configuredLevel\":\"debug\"}").contentType(MediaType.APPLICATION_JSON))
+				.andExpect(status().isNoContent()).andDo(
+						MockMvcRestDocumentation.document("loggers/setGroup",
+								requestFields(fieldWithPath("configuredLevel").description(
+										"Level for the logger group. May be omitted to clear the level of the loggers.")
+										.optional())));
+		verify(this.loggingSystem).setLogLevel("test.member1", LogLevel.DEBUG);
+		verify(this.loggingSystem).setLogLevel("test.member2", LogLevel.DEBUG);
+		resetLogger();
+	}
+
+	private void resetLogger() {
+		this.loggerGroups.get("test").configureLogLevel(null, (a, b) -> {
+		});
+	}
+
 	@Test
 	void clearLogLevel() throws Exception {
 		this.mockMvc
@@ -102,8 +146,13 @@ void clearLogLevel() throws Exception {
 	static class TestConfiguration {
 
 		@Bean
-		LoggersEndpoint endpoint(LoggingSystem loggingSystem) {
-			return new LoggersEndpoint(loggingSystem);
+		LoggersEndpoint endpoint(LoggingSystem loggingSystem, LoggerGroups groups) {
+			groups.putAll(getLoggerGroups());
+			return new LoggersEndpoint(loggingSystem, groups);
+		}
+
+		private Map<String, List<String>> getLoggerGroups() {
+			return Collections.singletonMap("test", Arrays.asList("test.member1", "test.member2"));
 		}
 
 	}

spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/logging/LoggersEndpoint.java

@@ -19,6 +19,7 @@
 import java.util.Collection;
 import java.util.Collections;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.NavigableSet;
 import java.util.Set;
@@ -30,6 +31,8 @@
 import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
 import org.springframework.boot.logging.LogLevel;
 import org.springframework.boot.logging.LoggerConfiguration;
+import org.springframework.boot.logging.LoggerGroup;
+import org.springframework.boot.logging.LoggerGroups;
 import org.springframework.boot.logging.LoggingSystem;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
@@ -39,20 +42,26 @@
  *
  * @author Ben Hale
  * @author Phillip Webb
+ * @author HaiTao Zhang
  * @since 2.0.0
  */
 @Endpoint(id = "loggers")
 public class LoggersEndpoint {
 
 	private final LoggingSystem loggingSystem;
 
+	private final LoggerGroups loggerGroups;
+
 	/**
 	 * Create a new {@link LoggersEndpoint} instance.
 	 * @param loggingSystem the logging system to expose
+	 * @param loggerGroups the logger group to expose
 	 */
-	public LoggersEndpoint(LoggingSystem loggingSystem) {
+	public LoggersEndpoint(LoggingSystem loggingSystem, LoggerGroups loggerGroups) {
 		Assert.notNull(loggingSystem, "LoggingSystem must not be null");
+		Assert.notNull(loggerGroups, "LoggerGroups must not be null");
 		this.loggingSystem = loggingSystem;
+		this.loggerGroups = loggerGroups;
 	}
 
 	@ReadOperation
@@ -64,19 +73,36 @@ public Map<String, Object> loggers() {
 		Map<String, Object> result = new LinkedHashMap<>();
 		result.put("levels", getLevels());
 		result.put("loggers", getLoggers(configurations));
+		result.put("groups", getGroups());
 		return result;
 	}
 
+	private Map<String, LoggerLevels> getGroups() {
+		Map<String, LoggerLevels> groups = new LinkedHashMap<>();
+		this.loggerGroups.forEach((group) -> groups.put(group.getName(),
+				new GroupLoggerLevels(group.getConfiguredLevel(), group.getMembers())));
+		return groups;
+	}
+
 	@ReadOperation
 	public LoggerLevels loggerLevels(@Selector String name) {
 		Assert.notNull(name, "Name must not be null");
+		LoggerGroup group = this.loggerGroups.get(name);
+		if (group != null) {
+			return new GroupLoggerLevels(group.getConfiguredLevel(), group.getMembers());
+		}
 		LoggerConfiguration configuration = this.loggingSystem.getLoggerConfiguration(name);
-		return (configuration != null) ? new LoggerLevels(configuration) : null;
+		return (configuration != null) ? new SingleLoggerLevels(configuration) : null;
 	}
 
 	@WriteOperation
 	public void configureLogLevel(@Selector String name, @Nullable LogLevel configuredLevel) {
 		Assert.notNull(name, "Name must not be empty");
+		LoggerGroup group = this.loggerGroups.get(name);
+		if (group != null && group.hasMembers()) {
+			group.configureLogLevel(configuredLevel, this.loggingSystem::setLogLevel);
+			return;
+		}
 		this.loggingSystem.setLogLevel(name, configuredLevel);
 	}
 
@@ -88,7 +114,7 @@ private NavigableSet<LogLevel> getLevels() {
 	private Map<String, LoggerLevels> getLoggers(Collection<LoggerConfiguration> configurations) {
 		Map<String, LoggerLevels> loggers = new LinkedHashMap<>(configurations.size());
 		for (LoggerConfiguration configuration : configurations) {
-			loggers.put(configuration.getName(), new LoggerLevels(configuration));
+			loggers.put(configuration.getName(), new SingleLoggerLevels(configuration));
 		}
 		return loggers;
 	}
@@ -100,21 +126,44 @@ public static class LoggerLevels {
 
 		private String configuredLevel;
 
-		private String effectiveLevel;
-
-		public LoggerLevels(LoggerConfiguration configuration) {
-			this.configuredLevel = getName(configuration.getConfiguredLevel());
-			this.effectiveLevel = getName(configuration.getEffectiveLevel());
+		public LoggerLevels(LogLevel configuredLevel) {
+			this.configuredLevel = getName(configuredLevel);
 		}
 
-		private String getName(LogLevel level) {
+		protected final String getName(LogLevel level) {
 			return (level != null) ? level.name() : null;
 		}
 
 		public String getConfiguredLevel() {
 			return this.configuredLevel;
 		}
 
+	}
+
+	public static class GroupLoggerLevels extends LoggerLevels {
+
+		private List<String> members;
+
+		public GroupLoggerLevels(LogLevel configuredLevel, List<String> members) {
+			super(configuredLevel);
+			this.members = members;
+		}
+
+		public List<String> getMembers() {
+			return this.members;
+		}
+
+	}
+
+	public static class SingleLoggerLevels extends LoggerLevels {
+
+		private String effectiveLevel;
+
+		public SingleLoggerLevels(LoggerConfiguration configuration) {
+			super(configuration.getConfiguredLevel());
+			this.effectiveLevel = getName(configuration.getEffectiveLevel());
+		}
+
 		public String getEffectiveLevel() {
 			return this.effectiveLevel;
 		}