Merge pull request for #32578 from rgoers

* pr/32578:
  Document Log4j2 extensions
  * Merge pull request for #32735:
    Polish 'Resolve URLs using Log4J2 mechanisms'
    Resolve URLs using Log4j2 mechanisms
  * Merge pull request for #32734:
    Polish 'Support profile specific Log4j2 configuration'
    Support profile specific Log4j2 configuration
  * Merge pull request for #32733:
    Polish 'Add Log4J2 PropertySource backed by the Spring Environment'
    Add Log4J2 PropertySource backed by the Spring Environment
  * Merge pull request for #32732:
    Polish 'Support Log4J2 string lookups from the Spring Environment'
    Support Log4J2 string lookups from the Spring Environment
  * Merge pull request for #32730:
    Polish 'Add Spring Environment to LoggerContext'
    Add Spring Environment to LoggerContext
  * Merge pull request for #32730:
    Polish 'Support 'log4j.configurationFile' system property'
    Support 'log4j.configurationFile' system property

Closes gh-32578

Author: philwebb

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/logging.adoc

@@ -1,7 +1,7 @@
 [[features.logging]]
 == Logging
 Spring Boot uses https://commons.apache.org/logging[Commons Logging] for all internal logging but leaves the underlying log implementation open.
-Default configurations are provided for {java-api}/java/util/logging/package-summary.html[Java Util Logging], https://logging.apache.org/log4j/2.x/[Log4J2], and https://logback.qos.ch/[Logback].
+Default configurations are provided for {java-api}/java/util/logging/package-summary.html[Java Util Logging], https://logging.apache.org/log4j/2.x/[Log4j2], and https://logback.qos.ch/[Logback].
 In each case, loggers are pre-configured to use console output with optional file output also available.
 
 By default, if you use the "`Starters`", Logback is used for logging.
@@ -158,7 +158,7 @@ As a result, specific configuration keys (such as `logback.configurationFile` fo
 [[features.logging.file-rotation]]
 === File Rotation
 If you are using the Logback, it is possible to fine-tune log rotation settings using your `application.properties` or `application.yaml` file.
-For all other logging system, you will need to configure rotation settings directly yourself (for example, if you use Log4J2 then you could add a `log4j2.xml` or `log4j2-spring.xml` file).
+For all other logging system, you will need to configure rotation settings directly yourself (for example, if you use Log4j2 then you could add a `log4j2.xml` or `log4j2-spring.xml` file).
 
 The following rotation policy properties are supported:
 
@@ -433,7 +433,7 @@ Profile sections are supported anywhere within the `<configuration>` element.
 Use the `name` attribute to specify which profile accepts the configuration.
 The `<springProfile>` tag can contain a profile name (for example `staging`) or a profile expression.
 A profile expression allows for more complicated profile logic to be expressed, for example `production & (eu-central | eu-west)`.
-Check the {spring-framework-docs}/core.html#beans-definition-profiles-java[reference guide] for more details.
+Check the {spring-framework-docs}/core.html#beans-definition-profiles-java[Spring Framework reference guide] for more details.
 The following listing shows three sample profiles:
 
 [source,xml,subs="verbatim",indent=0]
@@ -475,3 +475,76 @@ The following example shows how to expose properties for use within Logback:
 
 NOTE: The `source` must be specified in kebab case (such as `my.property-name`).
 However, properties can be added to the `Environment` by using the relaxed rules.
+
+
+
+[[features.logging.log4j2-extensions]]
+=== Log4j2 Extensions
+Spring Boot includes a number of extensions to Log4j2 that can help with advanced configuration.
+You can use these extensions in any `log4j2-spring.xml` configuration file.
+
+NOTE: Because the standard `log4j2.xml` configuration file is loaded too early, you cannot use extensions in it.
+You need to either use `log4j2-spring.xml` or define a configprop:logging.config[] property.
+
+NOTE: The extensions supersede the https://logging.apache.org/log4j/2.x/log4j-spring-boot/index.html[Spring Boot support] provided by Log4J.
+You should make sure not include the `org.apache.logging.log4j:log4j-spring-boot` module in your build.
+
+
+
+[[features.logging.log4j2-extensions.profile-specific]]
+==== Profile-specific Configuration
+The `<SpringProfile>` tag lets you optionally include or exclude sections of configuration based on the active Spring profiles.
+Profile sections are supported anywhere within the `<Configuration>` element.
+Use the `name` attribute to specify which profile accepts the configuration.
+The `<SpringProfile>` tag can contain a profile name (for example `staging`) or a profile expression.
+A profile expression allows for more complicated profile logic to be expressed, for example `production & (eu-central | eu-west)`.
+Check the {spring-framework-docs}/core.html#beans-definition-profiles-java[Spring Framework reference guide] for more details.
+The following listing shows three sample profiles:
+
+[source,xml,subs="verbatim",indent=0]
+----
+	<SpringProfile name="staging">
+		<!-- configuration to be enabled when the "staging" profile is active -->
+	</SpringProfile>
+
+	<SpringProfile name="dev | staging">
+		<!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
+	</SpringProfile>
+
+	<SpringProfile name="!production">
+		<!-- configuration to be enabled when the "production" profile is not active -->
+	</SpringProfile>
+----
+
+
+
+[[features.logging.log4j2-extensions.environment-properties-lookup]]
+==== Environment Properties Lookup
+If you want to refer to properties from your Spring `Environment` within your Log4j2 configuration you can use `spring:` prefixed https://logging.apache.org/log4j/2.x/manual/lookups.html[lookups].
+Doing so can be useful if you want to access values from your `application.properties` file in your Log4j2 configuration.
+
+The following example shows how to set a Log4j2 property named `applicationName` that reads `spring.application.name` from the Spring `Environment`:
+
+[source,xml,subs="verbatim",indent=0]
+----
+	<Properties>
+		<Property name="applicationName">${spring:spring.application.name}</property>
+	</Properties>
+----
+
+NOTE: The lookup key should be specified in kebab case (such as `my.property-name`).
+
+
+
+[[features.logging.log4j2-extensions.environment-peroperty-source]]
+==== Log4j2 System Properties
+Log4j2 supports a number of https://logging.apache.org/log4j/2.x/manual/configuration.html#SystemProperties[System Properties] that can be used configure various items.
+For example, the `log4j2.skipJansi` system property can be used to configure if the `ConsoleAppender` will try to use a https://github.com/fusesource/jansi[Jansi] output stream on Windows.
+
+All system properties that are loaded after the Log4J initialization can be obtained from the Spring `Environment`.
+For example, you could add `log4j2.skipJansi=false` to your `application.properties` file to have the `ConsoleAppender` use a Jansi on Windows.
+
+NOTE: The Spring `Environment` is only considered when system properties and OS environment variables do not contain the value being loaded.
+
+WARNING: System properties that are loaded during early Log4j2 initialization cannot reference the Spring `Environment`.
+For example, the property Log4j2 uses to allow the default Log4j2 implementation to be chosen is used before the Spring Environment is available.

spring-boot-project/spring-boot/src/main/java/org/springframework/boot/logging/log4j2/Log4J2LoggingSystem.java

@@ -17,13 +17,14 @@
 package org.springframework.boot.logging.log4j2;
 
 import java.io.IOException;
-import java.io.InputStream;
 import java.net.URL;
+import java.net.URLConnection;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Properties;
 import java.util.Set;
 import java.util.logging.ConsoleHandler;
 import java.util.logging.Handler;
@@ -42,9 +43,14 @@
 import org.apache.logging.log4j.core.config.LoggerConfig;
 import org.apache.logging.log4j.core.config.composite.CompositeConfiguration;
 import org.apache.logging.log4j.core.filter.AbstractFilter;
+import org.apache.logging.log4j.core.net.UrlConnectionFactory;
+import org.apache.logging.log4j.core.net.ssl.SslConfiguration;
+import org.apache.logging.log4j.core.net.ssl.SslConfigurationFactory;
+import org.apache.logging.log4j.core.util.AuthorizationProvider;
 import org.apache.logging.log4j.core.util.NameUtil;
 import org.apache.logging.log4j.jul.Log4jBridgeHandler;
 import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.util.PropertiesUtil;
 
 import org.springframework.boot.context.properties.bind.BindResult;
 import org.springframework.boot.context.properties.bind.Bindable;
@@ -56,8 +62,10 @@
 import org.springframework.boot.logging.LoggingInitializationContext;
 import org.springframework.boot.logging.LoggingSystem;
 import org.springframework.boot.logging.LoggingSystemFactory;
+import org.springframework.core.Conventions;
 import org.springframework.core.Ordered;
 import org.springframework.core.annotation.Order;
+import org.springframework.core.env.Environment;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.CollectionUtils;
@@ -71,6 +79,7 @@
  * @author Andy Wilkinson
  * @author Alexander Heusingfeld
  * @author Ben Hale
+ * @author Ralph Goers
  * @since 1.2.0
  */
 public class Log4J2LoggingSystem extends AbstractLoggingSystem {
@@ -81,6 +90,9 @@ public class Log4J2LoggingSystem extends AbstractLoggingSystem {
 
 	private static final String LOG4J_LOG_MANAGER = "org.apache.logging.log4j.jul.LogManager";
 
+	static final String ENVIRONMENT_KEY = Conventions.getQualifiedAttributeName(Log4J2LoggingSystem.class,
+			"environment");
+
 	private static final LogLevels<Level> LEVELS = new LogLevels<>();
 
 	static {
@@ -123,32 +135,29 @@ public Log4J2LoggingSystem(ClassLoader classLoader) {
 
 	@Override
 	protected String[] getStandardConfigLocations() {
-		return getCurrentlySupportedConfigLocations();
-	}
-
-	private String[] getCurrentlySupportedConfigLocations() {
-		List<String> supportedConfigLocations = new ArrayList<>();
-		addTestFiles(supportedConfigLocations);
-		supportedConfigLocations.add("log4j2.properties");
+		List<String> locations = new ArrayList<>();
+		locations.add("log4j2-test.properties");
 		if (isClassAvailable("com.fasterxml.jackson.dataformat.yaml.YAMLParser")) {
-			Collections.addAll(supportedConfigLocations, "log4j2.yaml", "log4j2.yml");
+			Collections.addAll(locations, "log4j2-test.yaml", "log4j2-test.yml");
 		}
 		if (isClassAvailable("com.fasterxml.jackson.databind.ObjectMapper")) {
-			Collections.addAll(supportedConfigLocations, "log4j2.json", "log4j2.jsn");
+			Collections.addAll(locations, "log4j2-test.json", "log4j2-test.jsn");
 		}
-		supportedConfigLocations.add("log4j2.xml");
-		return StringUtils.toStringArray(supportedConfigLocations);
-	}
-
-	private void addTestFiles(List<String> supportedConfigLocations) {
-		supportedConfigLocations.add("log4j2-test.properties");
+		locations.add("log4j2-test.xml");
+		locations.add("log4j2.properties");
 		if (isClassAvailable("com.fasterxml.jackson.dataformat.yaml.YAMLParser")) {
-			Collections.addAll(supportedConfigLocations, "log4j2-test.yaml", "log4j2-test.yml");
+			Collections.addAll(locations, "log4j2.yaml", "log4j2.yml");
 		}
 		if (isClassAvailable("com.fasterxml.jackson.databind.ObjectMapper")) {
-			Collections.addAll(supportedConfigLocations, "log4j2-test.json", "log4j2-test.jsn");
+			Collections.addAll(locations, "log4j2.json", "log4j2.jsn");
+		}
+		locations.add("log4j2.xml");
+		String propertyDefinedLocation = new PropertiesUtil(new Properties())
+				.getStringProperty(ConfigurationFactory.CONFIGURATION_FILE_PROPERTY);
+		if (propertyDefinedLocation != null) {
+			locations.add(propertyDefinedLocation);
 		}
-		supportedConfigLocations.add("log4j2-test.xml");
+		return StringUtils.toStringArray(locations);
 	}
 
 	protected boolean isClassAvailable(String className) {
@@ -227,6 +236,11 @@ public void initialize(LoggingInitializationContext initializationContext, Strin
 		if (isAlreadyInitialized(loggerContext)) {
 			return;
 		}
+		Environment environment = initializationContext.getEnvironment();
+		if (environment != null) {
+			getLoggerContext().putObjectIfAbsent(ENVIRONMENT_KEY, environment);
+			PropertiesUtil.getProperties().addPropertySource(new SpringEnvironmentPropertySource(environment));
+		}
 		loggerContext.getConfiguration().removeFilter(FILTER);
 		super.initialize(initializationContext, configLocation, logFile);
 		markAsInitialized(loggerContext);
@@ -290,11 +304,16 @@ private Configuration load(String location, LoggerContext context) throws IOExce
 	}
 
 	private ConfigurationSource getConfigurationSource(URL url) throws IOException {
-		InputStream stream = url.openStream();
 		if (FILE_PROTOCOL.equals(url.getProtocol())) {
-			return new ConfigurationSource(stream, ResourceUtils.getFile(url));
+			return new ConfigurationSource(url.openStream(), ResourceUtils.getFile(url));
 		}
-		return new ConfigurationSource(stream, url);
+		AuthorizationProvider authorizationProvider = ConfigurationFactory
+				.authorizationProvider(PropertiesUtil.getProperties());
+		SslConfiguration sslConfiguration = url.getProtocol().equals("https")
+				? SslConfigurationFactory.getSslConfiguration() : null;
+		URLConnection connection = UrlConnectionFactory.createConnection(url, 0, sslConfiguration,
+				authorizationProvider);
+		return new ConfigurationSource(connection.getInputStream(), url, connection.getLastModified());
 	}
 
 	private CompositeConfiguration createComposite(List<Configuration> configurations) {
@@ -467,6 +486,17 @@ private void markAsUninitialized(LoggerContext loggerContext) {
 		loggerContext.setExternalContext(null);
 	}
 
+	/**
+	 * Get the Spring {@link Environment} attached to the given {@link LoggerContext} or
+	 * {@code null} if no environment is available.
+	 * @param loggerContext the logger context
+	 * @return the Spring {@link Environment} or {@code null}
+	 * @since 3.0.0
+	 */
+	public static Environment getEnvironment(LoggerContext loggerContext) {
+		return (Environment) ((loggerContext != null) ? loggerContext.getObject(ENVIRONMENT_KEY) : null);
+	}
+
 	/**
 	 * {@link LoggingSystemFactory} that returns {@link Log4J2LoggingSystem} if possible.
 	 */

spring-boot-project/spring-boot/src/main/java/org/springframework/boot/logging/log4j2/SpringEnvironmentLookup.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2012-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.logging.log4j2;
+
+import org.apache.logging.log4j.core.LogEvent;
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.config.LoggerContextAware;
+import org.apache.logging.log4j.core.config.plugins.Plugin;
+import org.apache.logging.log4j.core.lookup.StrLookup;
+
+import org.springframework.core.env.Environment;
+import org.springframework.util.Assert;
+
+/**
+ * Lookup for Spring properties.
+ *
+ * @author Ralph Goers
+ * @author Phillip Webb
+ */
+@Plugin(name = "spring", category = StrLookup.CATEGORY)
+class SpringEnvironmentLookup implements LoggerContextAware, StrLookup {
+
+	private volatile Environment environment;
+
+	@Override
+	public String lookup(LogEvent event, String key) {
+		return lookup(key);
+	}
+
+	@Override
+	public String lookup(String key) {
+		Assert.state(this.environment != null, "Unable to obtain Spring Environment from LoggerContext");
+		return (this.environment != null) ? this.environment.getProperty(key) : null;
+	}
+
+	@Override
+	public void setLoggerContext(LoggerContext loggerContext) {
+		this.environment = Log4J2LoggingSystem.getEnvironment(loggerContext);
+	}
+
+}

spring-boot-project/spring-boot/src/main/java/org/springframework/boot/logging/log4j2/SpringEnvironmentPropertySource.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2012-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.logging.log4j2;
+
+import org.apache.logging.log4j.util.PropertySource;
+
+import org.springframework.core.env.Environment;
+import org.springframework.util.Assert;
+
+/**
+ * Returns properties from Spring.
+ *
+ * @author Ralph Goers
+ */
+class SpringEnvironmentPropertySource implements PropertySource {
+
+	/**
+	 * System properties take precedence followed by properties in Log4j properties files.
+	 */
+	private static final int PRIORITY = -100;
+
+	private final Environment environment;
+
+	SpringEnvironmentPropertySource(Environment environment) {
+		Assert.notNull(environment, "Environment must not be null");
+		this.environment = environment;
+	}
+
+	@Override
+	public int getPriority() {
+		return PRIORITY;
+	}
+
+	@Override
+	public String getProperty(String key) {
+		return this.environment.getProperty(key);
+	}
+
+	@Override
+	public boolean containsProperty(String key) {
+		return this.environment.containsProperty(key);
+	}
+
+}