From 4f072f4046365521dd587f8d56daa3bc26a501a4 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Fri, 26 Jun 2015 15:33:33 -0700 Subject: [PATCH] Update logging documentation Update logging documentation to show the new `-spring` convention and the Logback extensions. See gh-1788 See gh-2558 See gh-3338 --- spring-boot-docs/src/main/asciidoc/howto.adoc | 6 +- .../main/asciidoc/spring-boot-features.adoc | 82 ++++++++++++++++--- 2 files changed, 74 insertions(+), 14 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index aa4664cbd6..0f1c4357c2 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -1198,9 +1198,9 @@ using the "logging.config" property. [[howto-configure-logback-for-loggin]] === Configure Logback for logging -If you put a `logback.xml` in the root of your classpath it will be picked up from there. -Spring Boot provides a default base configuration that you can include if you just want -to set levels, e.g. +If you put a `logback-spring.xml` in the root of your classpath it will be picked up from +there. Spring Boot provides a default base configuration that you can include if you just +want to set levels, e.g. [source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 61d27dc408..370b963bc1 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -930,10 +930,12 @@ for details of how you can apply remapping in your own configuration. The various logging systems can be activated by including the appropriate libraries on the classpath, and further customized by providing a suitable configuration file in the root of the classpath, or in a location specified by the Spring `Environment` property -`logging.config`. (Note however that since logging is initialized *before* the -`ApplicationContext` is created, it isn't possible to control logging from -`@PropertySources` in Spring `@Configuration` files. System properties and the -conventional Spring Boot external configuration files work just fine.) +`logging.config`. + +NOTE: Since logging is initialized *before* the `ApplicationContext` is created, it isn't +possible to control logging from `@PropertySources` in Spring `@Configuration` files. +System properties and the conventional Spring Boot external configuration files work just +fine.) Depending on your logging system, the following files will be loaded: @@ -941,18 +943,26 @@ Depending on your logging system, the following files will be loaded: |Logging System |Customization |Logback -|`logback.xml` or `logback.groovy` +|`logback-spring.xml`, `logback-spring.groovy`, `logback.xml` or `logback.groovy` |Log4j -|`log4j.properties` or `log4j.xml` +|`log4j-spring.properties`, `log4j-spring.xml`, `log4j.properties` or `log4j.xml` |Log4j2 -|`log4j2.xml` +|`log4j2-spring.xml` or `log4j2.xml` |JDK (Java Util Logging) |`logging.properties` |=== +NOTE: When possible we recommend that you use the `-spring` variants for your logging +configuration (for example `logback-spring.xml` rather than `logback.xml`). If you use +standard configuration locations, Spring cannot completely control log initialization. + +WARNING: There are known classloading issues with Java Util Logging that cause problems +when running from an '`executable jar`'. We recommend that you avoid it if at all +possible. + To help with the customization some other properties are transferred from the Spring `Environment` to System properties: @@ -973,12 +983,63 @@ To help with the customization some other properties are transferred from the Sp environment variable). |=== + All the logging systems supported can consult System properties when parsing their configuration files. See the default configurations in `spring-boot.jar` for examples. -WARNING: There are known classloading issues with Java Util Logging that cause problems -when running from an '`executable jar`'. We recommend that you avoid it if at all -possible. + + +[[boot-features-logback-extensions]] +=== Logback extensions +Spring Boot includes a number of extensions to Logback which can help with advanced +configuration. You can use these extensions in your `logback-spring.xml` configuration +file. + +NOTE: You cannot use extensions in the standard `logback.xml` configuration file since +it's loaded too early. You need to either use `logback-spring.xml` or define a +`logging.config` property. + + + +==== Profile specific configuration +The `` tag allows you to optionally include or exclude sections of +configuration based on the active Spring profiles. Profile sections are supported anywhere +within the `` element. Use the `name` attribute to specify which profile +accepts the configuration. + +[source,xml,indent=0] +---- + + + + + + + +---- + + + +==== Environment properties +The `` tag allows you to surface properties from the Spring `Environment` +for use within Logback. This can be useful if you want to access values from your +`application.properties` file in your logback configuration. The tag works in a similar +way to Logback's standard `` tag, but rather than specifying a direct `value` +you specify the `source` of the property (from the `Environment`). You can use the `scope` +attribute if you need to store the property somewhere other than in `local` scope. + +[source,xml,indent=0] +---- + + + ${fluentHost} + ... + +---- + +TIP: The `RelaxedPropertyResolver` is used to access `Environment` properties. If specify +the `source` in dashed notation (`my-property-name`) all the relaxed variations will be +tried (`myPropertyName`, `MY_PROPERTY_NAME` etc). @@ -1126,7 +1187,6 @@ and it will be silently ignored by most build tools if you generate a jar. [[boot-features-spring-mvc-template-engines]] ==== Template engines - As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. Spring MVC supports a variety of templating technologies including Velocity, FreeMarker and JSPs. Many other templating engines also ship their own Spring MVC integrations.