= 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".

NOTE: Slf4j will only be auto-selected if Logback is in use.

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 and circumvent the discovery process just described.  It allows 2 different
mechanisms for this:

. First, JBoss Logging will look for a *System* setting with the key `org.jboss.logging.provider`, which can be set to
one of the following values:

    * jboss
    * jdk
    * log4j2
    * log4j
    * slf4j

. 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.

