This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Boot 3.3.2! |
Logging
Spring Boot uses Commons Logging for all internal logging but leaves the underlying log implementation open. Default configurations are provided for Java Util Logging, Log4j2, and 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.
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. |
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. |
Log Format
The default log output from Spring Boot resembles the following example:
2024-07-18T19:15:51.950Z INFO 108741 --- [myapp] [ main] o.s.b.d.f.logexample.MyApplication : Starting MyApplication using Java 17.0.12 with PID 108741 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2024-07-18T19:15:51.953Z INFO 108741 --- [myapp] [ main] o.s.b.d.f.logexample.MyApplication : No active profile set, falling back to 1 default profile: "default"
2024-07-18T19:15:54.465Z INFO 108741 --- [myapp] [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port 8080 (http)
2024-07-18T19:15:54.500Z INFO 108741 --- [myapp] [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2024-07-18T19:15:54.511Z INFO 108741 --- [myapp] [ main] o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/10.1.26]
2024-07-18T19:15:54.636Z INFO 108741 --- [myapp] [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2024-07-18T19:15:54.643Z INFO 108741 --- [myapp] [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2566 ms
2024-07-18T19:15:56.104Z INFO 108741 --- [myapp] [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8080 (http) with context path '/'
2024-07-18T19:15:56.123Z INFO 108741 --- [myapp] [ main] o.s.b.d.f.logexample.MyApplication : Started MyApplication in 5.134 seconds (process running for 6.021)
The following items are output:
-
Date and Time: Millisecond precision and easily sortable.
-
Log Level:
ERROR
,WARN
,INFO
,DEBUG
, orTRACE
. -
Process ID.
-
A
---
separator to distinguish the start of actual log messages. -
Application name: Enclosed in square brackets (logged by default only if
spring.application.name
is set) -
Application group: Enclosed in square brackets (logged by default only if
spring.application.group
is set) -
Thread name: Enclosed in square brackets (may be truncated for console output).
-
Correlation ID: If tracing is enabled (not shown in the sample above)
-
Logger name: This is usually the source class name (often abbreviated).
-
The log message.
Logback does not have a FATAL level.
It is mapped to ERROR .
|
If you have a spring.application.name property but don’t want it logged you can set logging.include-application-name to false .
|
If you have a spring.application.group property but don’t want it logged you can set logging.include-application-group to false .
|
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.
$ java -jar myapp.jar --debug
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).
Color-coded Output
If your terminal supports ANSI, color output is used to aid readability.
You can set spring.output.ansi.enabled
to a 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:
%clr(%5p)
The following table describes the mapping of log levels to colors:
Level | Color |
---|---|
|
Red |
|
Red |
|
Yellow |
|
Green |
|
Green |
|
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:
%clr(%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}){yellow}
The following colors and styles are supported:
-
blue
-
cyan
-
faint
-
green
-
magenta
-
red
-
yellow
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 logging.file.name
or logging.file.path
property (for example, in your application.properties
).
If both properties are set, logging.file.path
is ignored and only logging.file.name
is used.
The following table shows how the logging.*
properties can be used together:
logging.file.name |
logging.file.path |
Description |
---|---|---|
(none) |
(none) |
Console only logging. |
Specific file (for example, |
(none) |
Writes to the location specified by |
(none) |
Specific directory (for example, |
Writes |
Specific file |
Specific directory |
Writes to the location specified by |
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.
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.
|
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 |
---|---|
|
The filename pattern used to create log archives. |
|
If log archive cleanup should occur when the application starts. |
|
The maximum size of log file before it is archived. |
|
The maximum amount of size log archives can take before being deleted. |
|
The maximum number of archive log files to keep (defaults to 7). |
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
:
-
Properties
-
YAML
logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error
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
.
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 the SPRING_APPLICATION_JSON variable.
|
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
:
-
Properties
-
YAML
logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
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:
-
Properties
-
YAML
logging.level.tomcat=trace
logging:
level:
tomcat: "trace"
Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:
Name | Loggers |
---|---|
web |
|
sql |
|
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 context selectors which allow each Logger to be created in its own context.
You can use the 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:
-
Properties
-
YAML
logging.register-shutdown-hook=false
logging:
register-shutdown-hook: false
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: 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
.
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 |
|
Log4j2 |
|
JDK (Java Util Logging) |
|
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.
|
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 |
---|---|---|
|
|
The conversion word used when logging exceptions. |
|
|
If defined, it is used in the default log configuration. |
|
|
If defined, it is used in the default log configuration. |
|
|
The log pattern to use on the console (stdout). |
|
|
Appender pattern for log date format. |
|
|
The charset to use for console logging. |
|
|
The log level threshold to use for console logging. |
|
|
The log pattern to use in a file (if |
|
|
The charset to use for file logging (if |
|
|
The log level threshold to use for file logging. |
|
|
The format to use when rendering the log level (default |
|
|
The structured logging format to use for console logging. |
|
|
The structured logging format to use for file logging. |
|
|
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 |
---|---|---|
|
|
Pattern for rolled-over log file names (default |
|
|
Whether to clean the archive log files on startup. |
|
|
Maximum log file size. |
|
|
Total size of log backups to be kept. |
|
|
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:
If you want to use a placeholder in a logging property, you should use Spring Boot’s syntax and not the syntax of the underlying framework.
Notably, if you use Logback, you should use |
You can add MDC and other ad-hoc content to log lines by overriding only the
|
Structured Logging
Structured logging is a technique where the log output is written in a well-defined, often machine-readable format. Spring Boot supports structured logging and has support for the following formats out of the box:
To enable structured logging, set the property logging.structured.format.console
(for console output) or logging.structured.format.file
(for file output) to the id of the format you want to use.
Elastic Common Schema
Elastic Common Schema is a JSON based logging format.
To enable the Elastic Common Schema log format, set the appropriate format
property to ecs
:
-
Properties
-
YAML
logging.structured.format.console=ecs
logging.structured.format.file=ecs
logging:
structured:
format:
console: ecs
file: ecs
A log line looks like this:
{"@timestamp":"2024-01-01T10:15:00.067462556Z","log.level":"INFO","process.pid":39599,"process.thread.name":"main","service.name":"simple","log.logger":"org.example.Application","message":"No active profile set, falling back to 1 default profile: \"default\"","ecs.version":"8.11"}
This format also adds every key value pair contained in the MDC to the JSON object. You can also use the SLF4J fluent logging API to add key value pairs to the logged JSON object with the addKeyValue method.
Logstash JSON format
The Logstash JSON format is a JSON based logging format.
To enable the Logstash JSON log format, set the appropriate format
property to logstash
:
-
Properties
-
YAML
logging.structured.format.console=logstash
logging.structured.format.file=logstash
logging:
structured:
format:
console: logstash
file: logstash
A log line looks like this:
{"@timestamp":"2024-01-01T10:15:00.111037681+02:00","@version":"1","message":"No active profile set, falling back to 1 default profile: \"default\"","logger_name":"org.example.Application","thread_name":"main","level":"INFO","level_value":20000}
This format also adds every key value pair contained in the MDC to the JSON object. You can also use the SLF4J fluent logging API to add key value pairs to the logged JSON object with the addKeyValue method.
If you add markers, these will show up in a tags
string array in the JSON.
Custom Structured Logging formats
The structured logging support in Spring Boot is extensible, allowing you to define your own custom format.
To do this, implement the StructuredLoggingFormatter
interface. The generic type argument has to be ILoggingEvent
when using Logback and LogEvent
when using Log4j2 (that means your implementation is tied to a specific logging system).
Your implementation is then called with the log event and returns the String
to be logged, as seen in this example:
import ch.qos.logback.classic.spi.ILoggingEvent;
import org.springframework.boot.logging.structured.StructuredLogFormatter;
class MyCustomFormat implements StructuredLogFormatter<ILoggingEvent> {
@Override
public String format(ILoggingEvent event) {
return "time=" + event.getInstant() + " level=" + event.getLevel() + " message=" + event.getMessage() + "\n";
}
}
As you can see in the example, you can return any format, it doesn’t have to be JSON.
To enable your custom format, set the property logging.structured.format.console
or logging.structured.format.file
to the fully qualified class name of your implementation.
Your implementation can use some constructor parameters, which are injected automatically.
Please see the JavaDoc of StructuredLogFormatter
for more details.
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.
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 logging.config property.
|
The extensions cannot be used with Logback’s 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: |
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]]
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 reference guide for more details.
The following listing shows three sample profiles:
<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>
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:
<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>
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.
|
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.
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 logging.config property.
|
The extensions supersede the Spring Boot support provided by Log4J.
You should make sure not to include the org.apache.logging.log4j:log4j-spring-boot module in your build.
|
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 reference guide for more details.
The following listing shows three sample profiles:
<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>
Environment Properties Lookup
If you want to refer to properties from your Spring Environment
within your Log4j2 configuration you can use spring:
prefixed 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
and applicationGroup
that reads spring.application.name
and spring.application.group
from the Spring Environment
:
<Properties>
<Property name="applicationName">${spring:spring.application.name}</Property>
<Property name="applicationProperty">${spring:spring.application.property}</Property>
</Properties>
The lookup key should be specified in kebab case (such as my.property-name ).
|
Log4j2 System Properties
Log4j2 supports a number of System Properties that can be used to configure various items.
For example, the log4j2.skipJansi
system property can be used to configure if the ConsoleAppender
will try to use a Jansi output stream on Windows.
All system properties that are loaded after the Log4j2 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 Jansi on Windows.
The Spring Environment is only considered when system properties and OS environment variables do not contain the value being loaded.
|
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.
|