[[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].
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.
Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J, or SLF4J all work correctly.

TIP: There are a lot of logging frameworks available for Java.
Do not worry if the above list seems confusing.
Generally, you do not need to change your logging dependencies and the Spring Boot defaults work just fine.

TIP: When you deploy your application to a servlet container or application server, logging performed with the Java Util Logging API is not routed into your application's logs.
This prevents logging performed by the container or other applications that have been deployed to it from appearing in your application's logs.



[[features.logging.log-format]]
=== Log Format
The default log output from Spring Boot resembles the following example:

[indent=0]
----
include::{logging-format-output}[]
----

The following items are output:

* Date and Time: Millisecond precision and easily sortable.
* Log Level: `ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`.
* Process ID.
* A `---` separator to distinguish the start of actual log messages.
* Thread name: Enclosed in square brackets (may be truncated for console output).
* Logger name: This is usually the source class name (often abbreviated).
* The log message.

NOTE: Logback does not have a `FATAL` level.
It is mapped to `ERROR`.



[[features.logging.console-output]]
=== Console Output
The default log configuration echoes messages to the console as they are written.
By default, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged.
You can also enable a "`debug`" mode by starting your application with a `--debug` flag.

[source,shell,indent=0,subs="verbatim"]
----
	$ java -jar myapp.jar --debug
----

NOTE: You can also specify `debug=true` in your `application.properties`.

When the debug mode is enabled, a selection of core loggers (embedded container, Hibernate, and Spring Boot) are configured to output more information.
Enabling the debug mode does _not_ configure your application to log all messages with `DEBUG` level.

Alternatively, you can enable a "`trace`" mode by starting your application with a `--trace` flag (or `trace=true` in your `application.properties`).
Doing so enables trace logging for a selection of core loggers (embedded container, Hibernate schema generation, and the whole Spring portfolio).



[[features.logging.console-output.color-coded]]
==== Color-coded Output
If your terminal supports ANSI, color output is used to aid readability.
You can set `spring.output.ansi.enabled` to a {spring-boot-module-api}/ansi/AnsiOutput.Enabled.html[supported value] to override the auto-detection.

Color coding is configured by using the `%clr` conversion word.
In its simplest form, the converter colors the output according to the log level, as shown in the following example:

[source,indent=0,subs="verbatim"]
----
%clr(%5p)
----

The following table describes the mapping of log levels to colors:

|===
| Level | Color

| `FATAL`
| Red

| `ERROR`
| Red

| `WARN`
| Yellow

| `INFO`
| Green

| `DEBUG`
| Green

| `TRACE`
| Green
|===

Alternatively, you can specify the color or style that should be used by providing it as an option to the conversion.
For example, to make the text yellow, use the following setting:

[source,indent=0,subs="verbatim"]
----
	%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow}
----

The following colors and styles are supported:

* `blue`
* `cyan`
* `faint`
* `green`
* `magenta`
* `red`
* `yellow`



[[features.logging.file-output]]
=== File Output
By default, Spring Boot logs only to the console and does not write log files.
If you want to write log files in addition to the console output, you need to set a configprop:logging.file.name[] or configprop:logging.file.path[] property (for example, in your `application.properties`).

The following table shows how the `logging.*` properties can be used together:

.Logging properties
[cols="1,1,1,4"]
|===
| configprop:logging.file.name[] | configprop:logging.file.path[] | Example | Description

| _(none)_
| _(none)_
|
| Console only logging.

| Specific file
| _(none)_
| `my.log`
| Writes to the specified log file.
  Names can be an exact location or relative to the current directory.

| _(none)_
| Specific directory
| `/var/log`
| Writes `spring.log` to the specified directory.
  Names can be an exact location or relative to the current directory.
|===

Log files rotate when they reach 10 MB and, as with console output, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged by default.

TIP: Logging properties are independent of the actual logging infrastructure.
As a result, specific configuration keys (such as `logback.configurationFile` for Logback) are not managed by spring Boot.



[[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).

The following rotation policy properties are supported:

|===
| Name | Description

| configprop:logging.logback.rollingpolicy.file-name-pattern[]
| The filename pattern used to create log archives.

| configprop:logging.logback.rollingpolicy.clean-history-on-start[]
| If log archive cleanup should occur when the application starts.

| configprop:logging.logback.rollingpolicy.max-file-size[]
| The maximum size of log file before it is archived.

| configprop:logging.logback.rollingpolicy.total-size-cap[]
| The maximum amount of size log archives can take before being deleted.

| configprop:logging.logback.rollingpolicy.max-history[]
| The maximum number of archive log files to keep (defaults to 7).
|===



[[features.logging.log-levels]]
=== Log Levels
All the supported logging systems can have the logger levels set in the Spring `Environment` (for example, in `application.properties`) by using `+logging.level.<logger-name>=<level>+` where `level` is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL, or OFF.
The `root` logger can be configured by using `logging.level.root`.

The following example shows potential logging settings in `application.properties`:

[source,properties,indent=0,subs="verbatim",configprops,role="primary"]
.Properties
----
	logging.level.root=warn
	logging.level.org.springframework.web=debug
	logging.level.org.hibernate=error
----

[source,properties,indent=0,subs="verbatim",role="secondary"]
.Yaml
----
	logging:
	  level:
	    root: "warn"
	    org.springframework.web: "debug"
	    org.hibernate: "error"
----

It is also possible to set logging levels using environment variables.
For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springframework.web` to `DEBUG`.

NOTE: The above approach will only work for package level logging.
Since relaxed binding always converts environment variables to lowercase, it is not possible to configure logging for an individual class in this way.
If you need to configure logging for a class, you can use <<features#features.external-config.application-json, the `SPRING_APPLICATION_JSON`>> variable.



[[features.logging.log-groups]]
=== Log Groups
It is often useful to be able to group related loggers together so that they can all be configured at the same time.
For example, you might commonly change the logging levels for _all_ Tomcat related loggers, but you can not easily remember top level packages.

To help with this, Spring Boot allows you to define logging groups in your Spring `Environment`.
For example, here is how you could define a "`tomcat`" group by adding it to your `application.properties`:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	logging:
	  group:
	    tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"
----

Once defined, you can change the level for all the loggers in the group with a single line:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	logging:
	  level:
	    tomcat: "trace"
----

Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:

[cols="1,4"]
|===
| Name | Loggers

| web
| `org.springframework.core.codec`, `org.springframework.http`, `org.springframework.web`, `org.springframework.boot.actuate.endpoint.web`, `org.springframework.boot.web.servlet.ServletContextInitializerBeans`

| sql
| `org.springframework.jdbc.core`, `org.hibernate.SQL`, `org.jooq.tools.LoggerListener`
|===



[[features.logging.shutdown-hook]]
=== Using a Log Shutdown Hook
In order to release logging resources when your application terminates, a shutdown hook that will trigger log system cleanup when the JVM exits is provided.
This shutdown hook is registered automatically unless your application is deployed as a war file.
If your application has complex context hierarchies the shutdown hook may not meet your needs.
If it does not, disable the shutdown hook and investigate the options provided directly by the underlying logging system.
For example, Logback offers https://logback.qos.ch/manual/loggingSeparation.html[context selectors] which allow each Logger to be created in its own context.
You can use the configprop:logging.register-shutdown-hook[] property to disable the shutdown hook.
Setting it to `false` will disable the registration.
You can set the property in your `application.properties` or `application.yaml` file:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	logging:
	  register-shutdown-hook: false
----



[[features.logging.custom-log-configuration]]
=== Custom Log Configuration
The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring `Environment` property: configprop:logging.config[].

You can force Spring Boot to use a particular logging system by using the `org.springframework.boot.logging.LoggingSystem` system property.
The value should be the fully qualified class name of a `LoggingSystem` implementation.
You can also disable Spring Boot's logging configuration entirely by using a value of `none`.

NOTE: Since logging is initialized *before* the `ApplicationContext` is created, it is not possible to control logging from `@PropertySources` in Spring `@Configuration` files.
The only way to change the logging system or disable it entirely is through System properties.

Depending on your logging system, the following files are loaded:

|===
| Logging System | Customization

| Logback
| `logback-spring.xml`, `logback-spring.groovy`, `logback.xml`, or `logback.groovy`

| Log4j2
| `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 when running from an 'executable jar' if at all possible.

To help with the customization, some other properties are transferred from the Spring `Environment` to System properties.
This allows the properties to be consumed by logging system configuration. For example, setting `logging.file.name` in `application.properties` or `LOGGING_FILE_NAME` as an environment variable will result in the `LOG_FILE` System property being set.
The properties that are transferred are described in the following table:

|===
| Spring Environment | System Property | Comments

| configprop:logging.exception-conversion-word[]
| `LOG_EXCEPTION_CONVERSION_WORD`
| The conversion word used when logging exceptions.

| configprop:logging.file.name[]
| `LOG_FILE`
| If defined, it is used in the default log configuration.

| configprop:logging.file.path[]
| `LOG_PATH`
| If defined, it is used in the default log configuration.

| configprop:logging.pattern.console[]
| `CONSOLE_LOG_PATTERN`
| The log pattern to use on the console (stdout).

| configprop:logging.pattern.dateformat[]
| `LOG_DATEFORMAT_PATTERN`
| Appender pattern for log date format.

| configprop:logging.charset.console[]
| `CONSOLE_LOG_CHARSET`
| The charset to use for console logging.

| configprop:logging.pattern.file[]
| `FILE_LOG_PATTERN`
| The log pattern to use in a file (if `LOG_FILE` is enabled).

| configprop:logging.charset.file[]
| `FILE_LOG_CHARSET`
| The charset to use for file logging (if `LOG_FILE` is enabled).

| configprop:logging.pattern.level[]
| `LOG_LEVEL_PATTERN`
| The format to use when rendering the log level (default `%5p`).

| `PID`
| `PID`
| The current process ID (discovered if possible and when not already defined as an OS environment variable).
|===

If you use Logback, the following properties are also transferred:

|===
| Spring Environment | System Property | Comments

| configprop:logging.logback.rollingpolicy.file-name-pattern[]
| `LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN`
| Pattern for rolled-over log file names (default `$\{LOG_FILE}.%d\{yyyy-MM-dd}.%i.gz`).

| configprop:logging.logback.rollingpolicy.clean-history-on-start[]
| `LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START`
| Whether to clean the archive log files on startup.

| configprop:logging.logback.rollingpolicy.max-file-size[]
| `LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE`
| Maximum log file size.

| configprop:logging.logback.rollingpolicy.total-size-cap[]
| `LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP`
| Total size of log backups to be kept.

| configprop:logging.logback.rollingpolicy.max-history[]
| `LOGBACK_ROLLINGPOLICY_MAX_HISTORY`
| Maximum number of archive log files to keep.
|===


All the supported logging systems can consult System properties when parsing their configuration files.
See the default configurations in `spring-boot.jar` for examples:

* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/logback/defaults.xml[Logback]
* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/log4j2/log4j2.xml[Log4j 2]
* {spring-boot-code}/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/java/logging-file.properties[Java Util logging]

[TIP]
====
If you want to use a placeholder in a logging property, you should use <<features#features.external-config.files.property-placeholders,Spring Boot's syntax>> and not the syntax of the underlying framework.
Notably, if you use Logback, you should use `:` as the delimiter between a property name and its default value and not use `:-`.
====

[TIP]
====
You can add MDC and other ad-hoc content to log lines by overriding only the `LOG_LEVEL_PATTERN` (or `logging.pattern.level` with Logback).
For example, if you use `logging.pattern.level=user:%X\{user} %5p`, then the default log format contains an MDC entry for "user", if it exists, as shown in the following example.

[indent=0]
----
	2019-08-30 12:30:04.031 user:someone INFO 22174 --- [  nio-8080-exec-0] demo.Controller
	Handling authenticated request
----
====



[[features.logging.logback-extensions]]
=== Logback Extensions
Spring Boot includes a number of extensions to Logback that can help with advanced configuration.
You can use these extensions in your `logback-spring.xml` configuration file.

NOTE: Because the standard `logback.xml` configuration file is loaded too early, you cannot use extensions in it.
You need to either use `logback-spring.xml` or define a configprop:logging.config[] property.

WARNING: The extensions cannot be used with Logback's https://logback.qos.ch/manual/configuration.html#autoScan[configuration scanning].
If you attempt to do so, making changes to the configuration file results in an error similar to one of the following being logged:

[indent=0]
----
	ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
	ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]
----



[[features.logging.logback-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[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.logback-extensions.environment-properties]]
==== Environment Properties
The `<springProperty>` tag lets you expose properties from the Spring `Environment` for use within Logback.
Doing so 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 `<property>` tag.
However, rather than specifying a direct `value`, you specify the `source` of the property (from the `Environment`).
If you need to store the property somewhere other than in `local` scope, you can use the `scope` attribute.
If you need a fallback value (in case the property is not set in the `Environment`), you can use the `defaultValue` attribute.
The following example shows how to expose properties for use within Logback:

[source,xml,subs="verbatim",indent=0]
----
	<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
			defaultValue="localhost"/>
	<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
		<remoteHost>${fluentHost}</remoteHost>
		...
	</appender>
----

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.
