From cd1a7888c33a3f74945925f6e89a9c3abed87410 Mon Sep 17 00:00:00 2001 From: Emmanuel Bernard Date: Wed, 9 Feb 2005 17:03:31 +0000 Subject: [PATCH] Add Statistics documentation git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@5639 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- reference/en/modules/performance.xml | 125 +++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/reference/en/modules/performance.xml b/reference/en/modules/performance.xml index 85db654223..d8d1e36963 100644 --- a/reference/en/modules/performance.xml +++ b/reference/en/modules/performance.xml @@ -1117,4 +1117,129 @@ hibernate.cache.use_structured_entries true]]> + + Monitoring performance + Performance and optimization are nothing without monitoring. Without rational and concrete figures, + no good optimization is possible. Hibernate provides a full panel of figures related to Hibernate behaviors. + Hibernate statistics are related to a particular session factory. This makes perfect sense if we consider + the typical application as being build on top of one database / session factory. + + Monitoring a session factory + + Session factories publish their metrics through 2 basic ways. The first one use direct access to the + SessionFactory object. The statistics are attached to a session factory through + Statistics objects and accessed by sessionFactory.getStatistics(). + The second way, a bit more standard, use JMX to publish them through the StatisticsService + either one MBean per session factory, either one MBean for all session factories. Here is a minimalistic + code showing both ways (you must have a JMX server available). + + + + In the first case, we retrieve and use the MBean directly. In the second one, we must give the JNDI name + in which the session factory is held before using it. Use + hibernateStatsBean.setSessionFactoryJNDIName("my/JNDI/Name") + + + A session factory can be monitored or not. You can (de)activate the monitoring + + + + + at configuration time: hibernate.generate_statistics, default to false + + + + + + + at runtime time: sf.getStatistics().setStatisticsEnabled(true) + or hibernateStatsBean.setStatisticsEnabled(true) + + + + Statistics can be reset programatically using the clear() method. A summary + can be sent logger (info level) using the logSummary() method. + + + Metrics + + Hibernate provides a huge number of metrics, from the very basics to the very specialized ones. + All available counters are described in the Statistics interface API. + They are basically split into 3 categories: + + + + + metrics related to the general session usage (number of session open, session close, connections retrieved, ...), + + + + + metrics related to the entities, collections, queries, and caches as a whole (aka global metrics), + + + + + detailed metrics related to a particular entity, collection, query or cache region. + + + + + You can find (for example) the cache hit, miss and put ratio of entities, collections + and queries, the average time of a query, etc... Beware that the number of milliseconds is subject + to approximation in Java. Hibernate is tied to the JVM precision: it might lead to a 10 ms approx depending + on your platform. + + + Simple getters are used to access the global metrics (ie not tied to a particular entity, collection, + cache region). You access the metrics of a particular entity, collection or cache region through its name, + as shown in the above example, and through its HQL or SQL representation for queries. Please refer to the + Statistics, EntityStatistics, CollectionStatistics, + SecondLevelCacheStatistics and QueryStatistics API for more informations. + + + + In order to work on all detailed entities, collections, queries and region caches statistics, you can retrieve + the list of names of entities, collections, queries and region caches names having metrics. Use getQueries(), + getEntityNames(), getCollectionRoleNames(), or + getSecondLevelCacheRegionNames(). + + + + Understanding metrics + + You can find interesting informations while looking at metrics. An entity/collection/query with a high cache + miss ratio (cache miss superior to cache hit) should not be cached: the benefit of caching is not significant + for your application and use case. + An entity/collection/query with a cache put way superior to its cache hit should not be cached either: you spend + a lot of resources in caching without efficiently use it. + A session factory having more open sessions than closed ones shows a session leak which must be addressed. + A use case using lots of connections might show a good candidate for a conversion to the session per user + transaction pattern. + + +