Using the profiler is easy. First, we need to make the application that we profile is aware of the profiler. Then, just start the profiler.

Prerequisites

The profiler requires the following prerequisites:

• Java 5.0 or greater
• Hibernate 3.1 or greater
• Apache log4j

If you are using Spring and wish to use the optional Spring configuration, then you must be using Spring 2.0 or greater.

Log4j

If you are already using Apache log4j in your application, then you can skip to the next step. If you are not using log4j, then you need to setup your application to use it. You can download the lo4j from its website -- it is recommended that you use the latest 1.2 version. Once you have added the log4j JAR file to your application, then you will need to setup log4j using either a log4j.properties or log4j.xml file. The profiler is not dependent on how you setup log4j so you can set it up with any appenders and logging levels you wish. For more information on how to setup log4j, please refer to the log4j manual.

Web applications

If you are using Hibernate in a web application, you will need to add a listener to web.xml so that the profiler can associate a session with a web request. The following needs to be added to web.xml:

<listener>
 <listener-class>
  hibernatingrhinos.hibernate.profiler.web.HibernateProfilerListener 
 </listener-class>
</listener>

This step is not mandatory, however, be aware that the profiler will not associate your Hibernate sessions with the URL of the web requests if not added.

Spring

If you are using Hibernate with Spring 2.0 or greater, a namespace for the profiler is provided to ease integration. In your Spring configuration file (often named applicationContext.xml), you must first add the namespace to the configuration:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:hprof="http://www.nhprof.com/schema/hprof"
   xsi:schemaLocation="http://www.springframework.org/schema/beans 
   http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
   http://www.nhprof.com/schema/hprof http://www.nhprof.com/schema/hprof/hprof.xsd">
   ...
</beans>

Once the namespace has been added, add the configuration element to the your instance of LocalSessionFactoryBean or AnnotationSessionFactoryBean:

<bean id="sessionFactory" 
    class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
...
    <property name="hibernateProperties">
        <props>
        ...
        </props>
    </property>
    <hprof:profiler />
</bean>

If you want to profile the application from a remote host, then specify the IP address of the host:

<hprof:profiler address="10.0.0.2" />

This attribute handles the initialization and cleanup of the profiler, so no further configuration is necessary.

Hibernate

If you are not using Spring, you have two options for configuring the profiler.  One option is to configure the profiler the programmatically:

Configuration configuration = new Configuration();

HibernateProfiler.configure(configuration);

SessionFactory sessionFactory = configuration.configure().buildSessionFactory();

HibernateProfiler.initialize();

The configure call with modify your Hibernate settings so that the application can be profiled.  If you need configure the profiler manually, you can modifying the Hibernate configuration directly. The following properties should be set in your Hibernate configuration file:

<session-factory>
    ...
    <property name="cache.query_cache_factory">
    hibernatingrhinos.hibernate.profiler.cache.ProfilerQueryCacheFactory
    </property>
    <property name="generate_statistics">true</property>
</sessionFactory>

If you have defined the property jdbc.batch_size to a number greater than zero, then you should also define the following property:

<session-factory>
    ...
    <property name="jdbc.batch_size">50</property>
    <property name="jdbc.factory_class">
        hibernatingrhinos.hibernate.profiler.jdbc.ProfilerBatchingBatcherFactory
    </property>
</session-factory>

If you do not wish to enable statistics or are already using a custom batcher or query cache factory, then not enabling these features will not prevent you from using the profiler. However, there will be items that the profiler cannot detect or report on if these properties are not specified.

The profiler can also log JDBC parameters using a driver spy.  These feature is only supported if you are using Java 6 or greater.  To manually configure the driver spy, you need to modify your connection URL (this is done by both the programmatic configure method and Spring automatically) by appending 'jdbc:log4jdbc' to the front of your JDBC URL.  Below is an example of how to configure a SQL Server connection to log the parameters:

<session-factory>
  ...
  <prop key="hibernate.connection.url">jdbc:log4jdbc:sqlserver://localhost;instanceName=SQLExpress;user=sa;password=pass</prop>
</session-factory>

Initialization

Once the application has been setup to be profiled, you need to initialize the profiler in your code. This should only be done once when the application is starting up. Examples of a place to do this are the main() method of your application, a web application listener, or a servlet init() method. To initialize the profiler, place the following line of code within one of those start up methods:

HibernateProfiler.initialize();

There are additional method overrides for defining various configuration elements and for defining the port and address where the profiler client is running.

Profiling through config

This isn't the only way to profile an application; you can also configure your application for offline profiling through configuration.