482 lines
20 KiB
Plaintext
482 lines
20 KiB
Plaintext
[[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]
|
|
----
|
|
2019-03-05 10:57:51.112 INFO 45469 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomcat/7.0.52
|
|
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
|
|
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader : Root WebApplicationContext: initialization completed in 1358 ms
|
|
2019-03-05 10:57:51.698 INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean : Mapping servlet: 'dispatcherServlet' to [/]
|
|
2019-03-05 10:57:51.702 INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]
|
|
----
|
|
|
|
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'T'HH:mm:ss.SSSXXX}){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 http://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, as 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.
|