jdaugherty commented on code in PR #15757: URL: https://github.com/apache/grails-core/pull/15757#discussion_r3562562831
########## grails-doc/src/en/guide/conf/config/logging.adoc: ########## @@ -17,9 +17,37 @@ specific language governing permissions and limitations under the License. //// -Logging is handled by the https://logback.qos.ch[Logback logging framework] and can be configured with the `grails-app/conf/logback-spring.xml` file. See the https://docs.spring.io/spring-boot/how-to/logging.html[Spring Boot Logging] and https://docs.spring.io/spring-boot/reference/features/logging.html#features.logging.logback-extensions[Logging Extensions] for all the available options. - -The Grails Environments `development`, `test` and `production` can be used with <springProfile name="development"> to configure environment specific logging. This was one of the features lost when logback removed groovy configuration. +Logging is handled by the https://logback.qos.ch[Logback logging framework] and can be configured with the `grails-app/conf/logback-spring.xml` file that newly generated applications include. The file is optional: an application depends on `grails-logging`, which brings in Spring Boot's logging starter, so if the file is removed, Logback and Spring Boot's default Logback configuration (an `INFO` root logger and a colorized console pattern) are applied automatically with *zero configuration*. See the https://docs.spring.io/spring-boot/how-to/logging.html[Spring Boot Logging] and https://docs.spring.io/spring-boot/reference/features/logging.html#features.logging.logback-extensions[Logging Extensions] documentation for all the available options. + +For most needs, levels and patterns can be adjusted entirely from `application.yml` without any XML: + +[source,yaml] +.application.yml +---- +logging: + level: + root: INFO + com.example.myapp: DEBUG # your packages + org.hibernate.SQL: DEBUG # see the generated SQL + file: + name: logs/myapp.log # setting this activates Spring Boot's file appender Review Comment: "setting this activates Spring Boot's file appender" is only true in the zero-config case. When a `logback-spring.xml` is present — which is the default for newly generated applications, per the paragraph above — the custom file replaces Boot's `base.xml`, so `logging.file.name` sets the `LOG_FILE` property but nothing consumes it: no file appender appears until the user uncomments the `file-appender.xml` include in the generated file. Since this section presents the yaml as generally applicable, the comment will mislead the majority of readers who still have the generated file. Suggest scoping it, e.g. `# activates Boot's file appender when no logback-spring.xml is present (otherwise uncomment the file-appender include in that file)`. The same line in the upgrade-guide section is fine as-is, because there it sits under "With no configuration file present…". ########## grails-doc/src/en/guide/upgrading/upgrading80x.adoc: ########## @@ -1514,3 +1514,60 @@ Both hooks may be used on the same plugin during migration; when a registrar and **Bean-definition overriding edge case.** Grails defaults `spring.main.allow-bean-definition-overriding` to `true`, and under that default nothing changes: an application bean (from the application class, `resources.groovy` or `resources.xml`) that uses the same name as a plugin bean still replaces the plugin's bean. However, because plugin beans now register earlier and application beans register in a separate, later step, an application that explicitly sets `spring.main.allow-bean-definition-overriding` to `false` will see a `BeanDefinitionOverrideException` for an application bean that shadows a plugin bean — in previous releases the two definitions were merged before a single registry write, so the shadowing was silent even with overriding disabled. **Most applications and plugins need no action.** Behavior only changes where a plugin bean and a conditional Boot bean competed for the same name or type — the plugin bean now wins, which is almost always the intended outcome. + +==== 34. Zero-Config Logback Logging Is Now Supported + +Newly generated Grails 8 applications continue to include a starter `grails-app/conf/logback-spring.xml` file, but the file is now optional, and its content has been simplified to match Spring Boot's defaults. + +The starter file no longer duplicates Spring Boot's configuration: it composes Spring Boot's own `defaults.xml` and `console-appender.xml` and sets an `INFO` root level, while keeping a `<springProfile name="development">` block for environment-specific logging. Previous Grails releases generated a standalone configuration with an `ERROR` root level, which suppressed the `WARN` and `INFO` output — including framework startup warnings — that Spring Boot shows by default. Existing applications keep whatever configuration they already have. + +An application depends on `grails-logging`, which brings in Spring Boot's logging starter, so if `grails-app/conf/logback-spring.xml` is removed, Logback and Spring Boot's own default Logback configuration apply automatically. This matches the Spring Boot convention of needing no logging configuration file unless one is actually required. + +NOTE: A future major release may stop generating `grails-app/conf/logback-spring.xml` by default in favor of the zero-config behavior described here. Existing applications that contain the file are unaffected either way and continue to use it. + +With no configuration file present you get Spring Boot's defaults: an `INFO` root level and a colorized console pattern. Levels and patterns can be tuned from `application.yml` with no XML: + +[source,yaml] +.application.yml +---- +logging: + level: + root: INFO + com.example.myapp: DEBUG # your packages + org.hibernate.SQL: DEBUG # see the generated SQL + pattern: + console: "%d{HH:mm:ss.SSS} %-5level %logger{36} - %msg%n" + file: + name: logs/myapp.log # setting this activates Spring Boot's file appender +---- + +Per-environment logging also needs no XML. Grails environments map to Spring profiles, so an `environments` block in `application.yml` applies levels to a single environment — for example, verbose logging for your own packages in development only: + +[source,yaml] +.application.yml +---- +environments: + development: + logging: + level: + com.example.myapp: DEBUG +---- + +A profile-specific `grails-app/conf/application-development.yml` containing the same `logging.level` entries works as well. + +Keep (or re-add) a `logback-spring.xml` file when properties are not enough — for example custom appenders, structured/JSON output, or per-environment appender routing. Use the `-spring` variant (not plain `logback.xml`), because it is processed by Spring Boot and unlocks `<springProfile>` and `<springProperty>`: + +[source,xml] +.grails-app/conf/logback-spring.xml +---- +<?xml version="1.0" encoding="UTF-8"?> +<configuration> + <include resource="org/springframework/boot/logging/logback/defaults.xml"/> Review Comment: This example produces an application with no log output at all. Once a `logback-spring.xml` exists, it *replaces* Spring Boot's bundled configuration entirely, and `defaults.xml` only contributes conversion rules and a few logger levels — no appenders. With no `console-appender.xml` include and no `<root>` with an `appender-ref`, the root logger has no appenders, so everything (including the `org.hibernate.SQL` DEBUG the example enables) goes nowhere. Anyone who copies this snippet when re-adding the file will silence their application. The example should match the generated starter's shape: ```xml <configuration> <include resource="org/springframework/boot/logging/logback/defaults.xml"/> <include resource="org/springframework/boot/logging/logback/console-appender.xml"/> <root level="INFO"> <appender-ref ref="CONSOLE"/> </root> <springProfile name="development"> <logger name="org.hibernate.SQL" level="DEBUG"/> </springProfile> </configuration> ``` ########## grails-doc/src/en/guide/conf/config/logging.adoc: ########## @@ -17,9 +17,37 @@ specific language governing permissions and limitations under the License. //// -Logging is handled by the https://logback.qos.ch[Logback logging framework] and can be configured with the `grails-app/conf/logback-spring.xml` file. See the https://docs.spring.io/spring-boot/how-to/logging.html[Spring Boot Logging] and https://docs.spring.io/spring-boot/reference/features/logging.html#features.logging.logback-extensions[Logging Extensions] for all the available options. - -The Grails Environments `development`, `test` and `production` can be used with <springProfile name="development"> to configure environment specific logging. This was one of the features lost when logback removed groovy configuration. +Logging is handled by the https://logback.qos.ch[Logback logging framework] and can be configured with the `grails-app/conf/logback-spring.xml` file that newly generated applications include. The file is optional: an application depends on `grails-logging`, which brings in Spring Boot's logging starter, so if the file is removed, Logback and Spring Boot's default Logback configuration (an `INFO` root logger and a colorized console pattern) are applied automatically with *zero configuration*. See the https://docs.spring.io/spring-boot/how-to/logging.html[Spring Boot Logging] and https://docs.spring.io/spring-boot/reference/features/logging.html#features.logging.logback-extensions[Logging Extensions] documentation for all the available options. + +For most needs, levels and patterns can be adjusted entirely from `application.yml` without any XML: + +[source,yaml] +.application.yml +---- +logging: + level: + root: INFO + com.example.myapp: DEBUG # your packages + org.hibernate.SQL: DEBUG # see the generated SQL + file: + name: logs/myapp.log # setting this activates Spring Boot's file appender +---- + +Per-environment levels need no XML either. Grails environments map to Spring profiles, so an `environments` block in `application.yml` applies levels to a single environment — for example, verbose logging for your own packages in development only (a profile-specific `application-development.yml` works as well): + +[source,yaml] +.application.yml +---- +environments: + development: + logging: + level: + com.example.myapp: DEBUG +---- + +When properties are not enough — custom appenders, structured output, or per-environment appender routing — add a `grails-app/conf/logback-spring.xml` file. Use the `-spring` variant (not plain `logback.xml`), because it is processed by Spring Boot and unlocks `<springProfile>` and `<springProperty>`. The Grails environments `development`, `test` and `production` map to the corresponding Spring profiles, so `<springProfile name="development">` blocks configure environment-specific logging — one of the features lost when Logback removed Groovy configuration. + +TIP: When generating a project with https://start.grails.org[Grails Forge], select the *Zero-config Logback Logging* feature to omit the generated `grails-app/conf/logback-spring.xml` and rely entirely on Spring Boot's defaults plus `application.yml` tuning as described above. Review Comment: Neither doc spells out what selecting zero-config *gives up* relative to the generated file. The current text explains what still works (levels, patterns, per-environment levels via `environments`), but a reader choosing between the two modes can't see the boundary. Worth one sentence here listing what requires the XML file and is therefore lost until it's re-added: - `<springProfile>`-conditional *appenders/routing* (per-environment levels still work via yaml, but per-environment appenders don't) - the starter's development-profile `StackTrace` logger setting - activating a file appender purely via `logging.file.name` works in zero-config (Boot's `base.xml`), so that one actually only works *in* this mode — another reason to scope the comment on line 33. Everything else in this section applies to both modes, which is exactly why an explicit supported/unsupported line would make the choice easy. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
