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
|
== User Guides
|
||||||
|
|
||||||
* For information on generated (non-identifier) values, see the <<generated/GeneratedValues.adoc#,Generated Values Guide>>
|
* 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
|
* Others coming soon
|
||||||
|
|
||||||
== Tooling
|
== 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