HHH-8865 - Create topical guide for logging

documentation/src/main/asciidoc/topical/index.adoc

@@ -9,6 +9,7 @@ NOTE: This is still very much a work in progress. <<helping,Help>> is definitely
 == User Guides
 
 * For information on generated (non-identifier) values, see the <<generated/GeneratedValues.adoc#,Generated Values Guide>>
+* For information on logging, see <<logging/Logging.adoc#,Logging Guide>>
 * Others coming soon
 
 == Tooling

documentation/src/main/asciidoc/topical/logging/Logging.adoc

@@ -0,0 +1,97 @@
+= Logging Guide
+:toc:
+
+Since version 4.0, Hibernate has used the JBoss Logging library for its logging needs.  Like SLF4J and
+Jakarta's commons-logging, JBoss Logging is a "logging bridge" providing integration with numerous logging
+frameworks.  JBoss Logging was chosen because of its i18n support and its support for "message ids".  This is largely
+the seminal documentation of JBoss Logging since JBoss Logging currently provides no documentation of its own.
+
+
+== Supported Back-ends
+
+JBoss Logging understands the following back-ends as first-class citizens:
+
+. JBoss LogManager (mainly used only inside the WildFly app server)
+. Log4j 2
+. Log4j 1
+. Slf4j
+. JDK logging
+
+Note the order above, it is important.  By default JBoss Logging will search the ClassLoader for the availability of
+classes that indicate one of the above "providers" being available.  It does this in the order defined above.  So,
+for example,  if you have both JBoss LogManager and Slf4j available your classpath then JBoss LogManager will be used
+as it has the "higher precedence".
+
+This can sometimes lead to an unwanted logging set up to be used.  In such cases, JBoss Logging provides for you to
+tell it specifically which provider to use.
+
+
+=== Provider setting
+
+JBoss Logging will first look for a setting with the key `org.jboss.logging.provider`, which can be set to one of the
+following values:
+
+. jboss
+. jdk
+. log4j2
+. log4j
+. slf4j
+
+
+=== JDK Service
+
+Next, JBoss Logging will look for a JDK service (see javadocs for +java.util.ServiceLoader+ for details) for its
+"provider" contract (+org.jboss.logging.Provider+).  If multiple are available, it will use the first one returned by
+the ClassLoader.
+
+
+== Usage
+
+Most of the time, the discovery process JustWorks.  The discovery process relies on the jars available on the classpath.
+The jboss-logging jar is a required dependency of Hibernate and therefore will always need to be on the classpath.
+
+* To use JBoss Logging with Log4j, the log4j jar would also need to be available on the classpath.
+* To use JBoss Logging with Log4j2, the log4j2 jar would also need to be available on the classpath.
+* To use JBoss Logging with Slf4j, the slf4j-api jar would also need to be available on the classpath *plus* any needed
+slf4j backend.
+
+JDK Logging would be used if none of the other framework jars are available.
+
+
+== Log Categories of Interest
+
+It is recommended that you familiarize yourself with the log messages sent from Hibernate.  A lot of work has been put
+into making the Hibernate loggiong as detailed as possible, without making it unreadable.  It is an essential
+troubleshooting device.  Some log categories of particular interest include:
+
+.Hibernate Log Categories of Interest
+|===
+|Category|Description
+
+|org.hibernate.SQL
+|Log all SQL statements as they are executed with through JDBC
+
+|org.hibernate.type.descriptor.sql
+|Log all values as they are bound to JDBC parameters and extracted from JDBC results
+
+|org.hibernate.tool.hbm2ddl
+|Log all SQL DDL statements as they are executed during execution of any of the schema migration tools
+
+|org.hibernate.pretty
+|Log the state of all entities (max 20 entities) associated with the session at flush time
+
+|org.hibernate.cache
+|Log all second-level cache activity
+
+|org.hibernate.hql.internal.ast.AST
+|Log HQL and SQL ASTs during query parsing
+
+|org.hibernate
+|Log everything. This is a lot of information but it is useful for troubleshooting
+|===
+
+
+== Message Id Index
+
+Coming soon.
+