HHH-8865 - Create topical guide for logging
(cherry picked from commit 2d26135a5a)
This commit is contained in:
Steve Ebersole
parent
cd964a9aca
commit
d0a699de68
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue