From 2d26135a5ae518fb3a1a280f587c8eac5323b199 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Wed, 15 Jan 2014 12:42:44 -0600 Subject: [PATCH] HHH-8865 - Create topical guide for logging --- .../src/main/asciidoc/topical/index.adoc | 1 + .../asciidoc/topical/logging/Logging.adoc | 97 +++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 documentation/src/main/asciidoc/topical/logging/Logging.adoc diff --git a/documentation/src/main/asciidoc/topical/index.adoc b/documentation/src/main/asciidoc/topical/index.adoc index 1cf2e3b4c2..b70c5e69fc 100644 --- a/documentation/src/main/asciidoc/topical/index.adoc +++ b/documentation/src/main/asciidoc/topical/index.adoc @@ -9,6 +9,7 @@ NOTE: This is still very much a work in progress. <> is definitely == User Guides * For information on generated (non-identifier) values, see the <> +* For information on logging, see <> * Others coming soon == Tooling diff --git a/documentation/src/main/asciidoc/topical/logging/Logging.adoc b/documentation/src/main/asciidoc/topical/logging/Logging.adoc new file mode 100644 index 0000000000..201d528641 --- /dev/null +++ b/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. +