This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 9f29bd6404 Add Hibernate integration page (#2626)
9f29bd6404 is described below
commit 9f29bd64040d071f1376e4de6d627090febb400d
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 | 39 ++++++++++
.../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, 273 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..c03ce0ac6f
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.properties
@@ -0,0 +1,39 @@
+#
+# 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.
+#
+appender.0.type = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = PatternLayout
+
+# Log just the SQL
+logger.0.name = org.hibernate.SQL
+logger.0.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!
+#logger.1.name = org.hibernate.type
+#logger.1.level = TRACE
+#logger.2.name = org.hibernate.orm.jdbc.bind
+#logger.2.level = TRACE
+#logger.3.name = org.hibernate.orm.jdbc.bind
+#logger.3.level = TRACE
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.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 24883c4962..1c0af5b572 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -64,6 +64,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 47e84aee41..97881b7e8a 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
