diff --git a/spring-geode-docs/src/docs/asciidoc/_includes/logging.adoc b/spring-geode-docs/src/docs/asciidoc/_includes/logging.adoc index 10694827..69df940c 100644 --- a/spring-geode-docs/src/docs/asciidoc/_includes/logging.adoc +++ b/spring-geode-docs/src/docs/asciidoc/_includes/logging.adoc @@ -75,7 +75,7 @@ So, how do you configure logging for {geode-name}? Three things are required to get {geode-name} to log output: -. You must declare a logging provider (such as Logback) on your Spring Boot application classpath. +. You must declare a logging provider (such as Logback, or Log4j) on your Spring Boot application classpath. . (optional) You can declare an adapter (a bridge JAR) between Log4j and your logging provider if your declared logging provider is not Apache Log4j. + @@ -96,22 +96,27 @@ NOTE: {geode-name}'s `geode-log4j` module covers the required configuration for (`org.apache.logging.log4j:log4j-core`) as the logging provider. The `geode-log4j` module even provides a default `log4j2.xml` configuration file to configure Loggers, Appenders, and log levels for {geode-name}. -If you declare Spring Boot's own `org.springframework.boot:spring-boot-starter-logging` on your application classpath, -it covers steps 1 and 2 above. +If you declare Spring Boot's own `org.springframework.boot:spring-boot-starter-logging` on your application +classpath, it covers steps 1 and 2 above. The `spring-boot-starter-logging` dependency declares Logback as the logging provider and automatically adapts (bridges) `java.util.logging` (JUL) and Apache Log4j to SLF4J. However, you still need to supply logging provider configuration (such as a `logback.xml` file for Logback) to configure logging not only for your Spring Boot application but for {geode-name} as well. +NOTE: If no user-specified logging configuration is supplied, Logback will apply default configuration +using the `BasicConfigurator`. See Logback https://logback.qos.ch/manual/configuration.html#auto_configuration[documentation] +for complete details. + SBDG has simplified the setup of {geode-name} logging. You need only declare the `org.springframework.geode:spring-geode-starter-logging` dependency on your Spring Boot application classpath. -Unlike {geode-name}'s default Log4j XML configuration file (`log4j2.xml`), SBDG's provided `logback.xml` configuration -file is properly parameterized, letting you adjust log levels as well as add Appenders. +Unlike {geode-name}'s default Log4j XML configuration file (`log4j2.xml` from `geode-log4j`), SBDG's provided +`logback.xml` configuration file is properly parameterized, letting you adjust log levels, add Appenders +as well as adjust other logging settings. In addition, SBDG's provided Logback configuration uses templates so that you can compose your own logging configuration -while still including snippets from SBDG's provided logging configuration metadata, such as Loggers and Appenders. +while still including snippets from SBDG's provided logging configuration, such as Loggers and Appenders. [[geode-logging-configuration-log-levels]] ==== Configuring Log Levels @@ -129,7 +134,7 @@ SBDG's Logback configuration defines three Loggers to control the log output fro - + ---- ==== @@ -142,7 +147,7 @@ during the runtime operation of {geode-name}. By default, it logs output at `INF The `org.jgroups` Logger is used to log output from {geode-name}'s message distribution and membership system. {geode-name} uses JGroups for membership and message distribution between peer members (nodes) in the cluster -(distributed system). By default, JGroups logs output at `ERROR`. +(distributed system). By default, JGroups logs output at `WARN`. You can configure the log level for the `com.gemstone.gemfire` and `org.apache.geode` Loggers by setting the `spring.boot.data.gemfire.log.level` property. You can independently configure the `org.jgroups` Logger by setting @@ -195,30 +200,118 @@ or later. As mentioned earlier, SBDG lets you compose your own logging configuration from SBDG's default Logback configuration metadata. -SBDG conveniently bundles the Loggers and Appenders from SBDG's logging starter into a template file that you can -include into your own custom Logback XML configuration file. +SBDG conveniently bundles the Properties, Loggers and Appenders from SBDG's logging starter into several template files +that you can include into your own custom Logback XML configuration file. -The Logback template file appears as follows: +The Logback configuration template files are broken down into: -.logback-include.xml +* `org/springframework/geode/logging/slf4j/logback/properties-include.xml` +* `org/springframework/geode/logging/slf4j/logback/loggers-include.xml` +* `org/springframework/geode/logging/slf4j/logback/appenders-include.xml` + +WARNING: As of SBDG `2.7`, the `logback-include.xml` file has been deprecated. + +The `properties-include.xml` defines Logback "_local_" scoped properties or variables common to SBDG's configuration +of {geode-name} logging. + +.properties-include.xml ==== [source,xml] ---- -include::{starter-logging-resources-dir}/logback-include.xml[] +include::{starter-logging-resources-dir}/org/springframework/geode/logging/slf4j/logback/properties-include.xml[] ---- ==== -Then you can include this Logback configuration snippet in an application-specific Logback XML configuration file, -as follows: +The `loggers-include.xml` file defines the `Loggers` used to log output from {geode-name} components. -.logback.xml +.loggers-include.xml ==== [source,xml] ---- -include::{starter-logging-resources-dir}/logback.xml[] +include::{starter-logging-resources-dir}/org/springframework/geode/logging/slf4j/logback/logger-include.xml[] ---- ==== +The `appenders-include.xml` file defines Appenders to send the log output to. If Spring Boot is on the application +classpath, then Spring Boot logging configuration will define the "CONSOLE" `Appender`, otherwise, SBDG will provide +a default definition. + +The "geode" `Appender` defines the {geode-name} logging pattern as seen in {geode-name}'s Log4j configuration. + +.appenders-include.xml +==== +[source,xml] +---- +include::{starter-logging-resources-dir}/org/springframework/geode/logging/slf4j/logback/appender-include.xml[] +---- +==== + +Then you can include any of SBDG'S Logback configuration metadata files as needed in your application-specific +Logback XML configuration file, as follows: + +.application-specific logback.xml +==== +[source,xml] +---- + + + + + + + + + + + + + + + + +---- +==== + +[[geode-logging-configuration-customizing]] +==== Customizing Logging Configuration + +It is now possible to customize the configuration of {geode-name} logging using properties defined in +a `spring-geode-logging.properties` file included on the Spring Boot application classpath. + +Any of the properties defined in `org/springframework/geode/logging/slf4j/logback/properties-include.xml` (shown above), +such as `APACHE_GEODE_LOG_PATTERN`, or the `spring.geode.logging.appender-ref` property, can be set. + +For instance, and by default, {geode-name} components log output using the Spring Boot log pattern. However, if you +prefer the fine-grained details of Apache Geode's logging behavior, you can change the `Appender` used by +the {geode-name} `Logger's` to use the pre-defined "geode" `Appender` instead. Simply set +the `spring-geode.logging.appender-ref` property to "geode" in a `spring-geode-logging.properties` file +on your Spring Boot application classpath, as follows: + +.spring-geode-logging.properties +==== +[source,properties] +---- +# spring-geode-logging.properties +spring.geode.logging.appender-ref=geode +---- +==== + +Alternatively, if you want to configure the log output of your entire Spring Boot application, including log output +from all {geode-name} components, then you can set the `SPRING_BOOT_LOG_PATTERN` property, or Spring Boot's +`CONSOLE_LOG_PATTERN` property, in `spring-geode-logging.properties`, as follows: + +.spring-geode-logging.properties +==== +[source,properties] +---- +# spring-geode-logging.properties +CONSOLE_LOG_PATTERN=TEST - %msg%n +---- +==== + +NOTE: The `spring-geode-logging.properties` file is only recognized when the `spring-geode-starter-logging` module +is used. + [[geode-logging-slf4j-logback-api-support]] === SLF4J and Logback API Support