This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit a504bca850fcb4c340cdd0ceb3ca8fb48160d50d Author: Volkan Yazıcı <[email protected]> AuthorDate: Thu May 30 13:18:24 2024 +0200 Add Hibernate integration page (#2626) --- .../modules/ROOT/examples/hibernate/log4j2.json | 46 ++++++++++++ .../ROOT/examples/hibernate/log4j2.properties | 38 ++++++++++ .../modules/ROOT/examples/hibernate/log4j2.xml | 53 ++++++++++++++ .../modules/ROOT/examples/hibernate/log4j2.yaml | 48 +++++++++++++ src/site/antora/modules/ROOT/nav.adoc | 1 + src/site/antora/modules/ROOT/pages/hibernate.adoc | 84 ++++++++++++++++++++++ .../modules/ROOT/pages/manual/installation.adoc | 4 +- 7 files changed, 272 insertions(+), 2 deletions(-) diff --git a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json new file mode 100644 index 0000000000..593aa3c048 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json @@ -0,0 +1,46 @@ +{ + "Configuration": { + "Appenders": { + "Console": { + "name": "CONSOLE", + "PatternLayout": {} + } + }, + "Loggers": { + "Logger": [ + + // Log just the SQL + { + "name": "org.hibernate.SQL", + "level": "DEBUG" + }, + + // Log JDBC bind parameters and extracted values + // + // Warning! <1> + // JDBC bind parameters can contain sensitive data: + // Passwords, credit card numbers, etc. + // Use these logger configurations with care! + //{ + // "name": "org.hibernate.type", + // "level": "TRACE" + //}, + //{ + // "name": "org.hibernate.orm.jdbc.bind", + // "level": "TRACE" + //}, + //{ + // "name": "org.hibernate.orm.jdbc.extract", + // "level": "TRACE" + //} + + ], + "Root": { + "level": "WARN" + }, + "AppenderRef": { + "ref": "CONSOLE" + } + } + } +} diff --git a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.properties b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.properties new file mode 100644 index 0000000000..f4d702f401 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.properties @@ -0,0 +1,38 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to you under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +Appenders.Console.name = CONSOLE +Appenders.Console.PatternLayout.type = PatternLayout + +# Log just the SQL +Loggers.1.name = org.hibernate.SQL +Loggers.1.level = DEBUG + +# Log JDBC bind parameters and extracted values +# +# Warning! <1> +# JDBC bind parameters can contain sensitive data! +# Passwords, credit card numbers, etc. +# Use these logger configurations with great care! +#Loggers.2.name = org.hibernate.type +#Loggers.2.level = TRACE +#Loggers.3.name = org.hibernate.orm.jdbc.bind +#Loggers.3.level = TRACE +#Loggers.4.name = org.hibernate.orm.jdbc.bind +#Loggers.4.level = TRACE + +Loggers.Root.level = WARN +Loggers.Root.AppenderRef.ref = CONSOLE diff --git a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.xml b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.xml new file mode 100644 index 0000000000..869b5c1001 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.xml @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to you under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + --> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + https://logging.apache.org/xml/ns + https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + + <Appenders> + <Console name="CONSOLE"> + <PatternLayout/> + </Console> + </Appenders> + + <Loggers> + + <!-- Log just the SQL --> + <Logger name="org.hibernate.SQL" level="DEBUG"/> + + <!-- Log JDBC bind parameters and extracted values + + Warning! <1> + JDBC bind parameters can contain sensitive data! + Passwords, credit card numbers, etc. + Use these logger configurations with care! --> + <!-- + <Logger name="org.hibernate.type" level="TRACE"/> + <Logger name="org.hibernate.orm.jdbc.bind" level="TRACE"/> + <Logger name="org.hibernate.orm.jdbc.extract" level="TRACE"/> + --> + + <Root level="WARN"> + <AppenderRef ref="CONSOLE"/> + </Root> + + </Loggers> + +</Configuration> diff --git a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.yaml b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.yaml new file mode 100644 index 0000000000..b971d4bd18 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.yaml @@ -0,0 +1,48 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to you under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +Configuration: + + Appenders: + Console: + name: "CONSOLE" + PatternLayout: {} + + Loggers: + + Logger: + + # Log just the SQL + - name: "org.hibernate.SQL" + level: "DEBUG" + + # Log JDBC bind parameters and extracted values + # + # Warning! <1> + # JDBC bind parameters can contain sensitive data! + # Passwords, credit card numbers, etc. + # Use these logger configurations with care! + #- name: "org.hibernate.type" + # level: "TRACE" + #- name: "org.hibernate.orm.jdbc.bind" + # level: "TRACE" + #- name: "org.hibernate.orm.jdbc.extract" + # level: "TRACE" + + Root: + level: "WARN" + AppenderRef: + ref: "CONSOLE" diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index 0f893a52b9..a8acf7f0e0 100644 --- a/src/site/antora/modules/ROOT/nav.adoc +++ b/src/site/antora/modules/ROOT/nav.adoc @@ -52,6 +52,7 @@ * xref:manual/migration.adoc[] * xref:migrate-from-logback.adoc[] * xref:migrate-from-slf4j.adoc[] +* xref:hibernate.adoc[] * xref:manual/cloud.adoc[] * xref:development.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/hibernate.adoc b/src/site/antora/modules/ROOT/pages/hibernate.adoc new file mode 100644 index 0000000000..dc9531d293 --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/hibernate.adoc @@ -0,0 +1,84 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + +:hibernate-manual-url: https://docs.jboss.org/hibernate/orm/6.5/userguide/html_single/Hibernate_User_Guide.html +:jboss-logging-url: https://github.com/jboss-logging/jboss-logging + += Integrating with Hibernate + +https://hibernate.org[Hibernate] is an Object/Relational Mapping (ORM) solution for Java environments. +It uses https://github.com/jboss-logging/jboss-logging[JBoss Logging] as its logging API. +If you have a working xref:manual/installation.adoc#impl-core[Log4j installation], JBoss Logging requires no extra installation steps on your part, since it is shipped with an integrated bridge to Log4j API – see https://github.com/jboss-logging/jboss-logging/blob/main/README.adoc#supported-log-managers[Supported Log Managers by JBoss Logging] for more information. + +.Struggling with the logging API, implementation, and bridge concepts? Click for an introduction. +[%collapsible] +==== +include::partial$concepts.adoc[tag=!software-type] +==== + +[#config] +== Configuration + +After successfully wiring Hibernate – to be precise, JBoss Logging – to log using Log4j API, you can fine-tune the verbosity of Hibernate loggers in your Log4j Core installation to accommodate your needs: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/hibernate/log4j2.xml[`log4j2.xml`] configuring Hibernate-specific loggers +[source,xml] +---- +include::example$hibernate/log4j2.xml[lines=30..45,indent=0] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/hibernate/log4j2.json[`log4j2.json`] configuring Hibernate-specific loggers +[source,xml] +---- +include::example$hibernate/log4j2.json[lines=9..36,indent=0] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/hibernate/log4j2.yaml[`log4j2.yaml`] configuring Hibernate-specific loggers +[source,xml] +---- +include::example$hibernate/log4j2.yaml[lines=24..44,indent=0] +---- + +Java properties:: ++ +.Snippet from an example {antora-examples-url}/hibernate/log4j2.properties[`log4j2.properties`] configuring Hibernate-specific loggers +[source,xml] +---- +include::example$hibernate/log4j2.properties[lines=21..37] +---- +==== +<1> Due to the sensitivity of the data involved, you are strongly advised to use these logger configurations **only in development environments**. + +See {hibernate-manual-url}#best-practices-logging[the Logging Best Practices section in Hibernate Manual] for further details. + +[#show-sql] +[WARNING] +==== +We strongly advise you to *avoid using {hibernate-manual-url}#settings-hibernate.show_sql[the `hibernate.show_sql` property]!* +(It maps to `spring.jpa.show-sql` in Spring Boot.) +`hibernate.show_sql` writes to the standard error output stream, not to the logging API. +Logger-based configuration exemplified above gives a finer-grained control over logging and integrates with the logging system. +https://stackoverflow.com/q/73734494/1278899[Combining `hibernate.show_sql` with logger-based configuration duplicates the logging effort.] +==== diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index 96d2d28342..e42e717fa7 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -394,8 +394,8 @@ Gradle users should refer to the https://docs.gradle.org/current/userguide/platf [#impl-core-bridge-jboss-logging] ===== Installing JBoss Logging-to-Log4j bridge -The JBoss Logging API is shipped with an integrated bridge to Log4j API and requires no steps on your part. -See https://github.com/jboss-logging/jboss-logging?tab=readme-ov-file#supported-log-managers[Supported Log Managers] for more information. +JBoss Logging is shipped with an integrated bridge to Log4j API and requires no steps on your part. +See https://github.com/jboss-logging/jboss-logging/blob/main/README.adoc#supported-log-managers[Supported Log Managers] for more information. [#impl-core-spring-boot] ==== Installing Log4j Core for Spring Boot applications
