<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory">Chapter 15. eXo JCR statistics</title><link rel="stylesheet" href="css/jbossorg.css" type="text/css"/><meta xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" name="generator" content="DocBook XSL Stylesheets V1.72.0"/><link rel="start" href="index.html" title="eXoJCR Reference Manual"/><link rel="up" href="part-jcr.html" title="Part I. eXoJCR"/><link rel="prev" href="ch-transaction-manager.html" title="Chapter 14. TransactionManagerLookup"/><link rel="next" href="part-kernel.html" title="Part II. eXoKernel"/></head><body><p id="title"><a href="http://www.jboss.org" class="site_href"><strong>JBoss.org</strong></a><a href="http://docs.jboss.org/" class="doc_href"><strong>Community Documentation</strong></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="ch-transaction-manager.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="part-kernel.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="ch_statistics"/>Chapter 15. eXo JCR statistics</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ch-statistics#d0e2102">15.1. Statistics on the Database Access Layer</a></span></dt><dt><span class="section"><a href="ch-statistics#d0e2288">15.2. Statistics on the JCR API accesses</a></span></dt><dt><span class="section"><a href="ch-statistics#d0e2376">15.3. Statistics Manager</a></span></dt></dl></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="d0e2102"/>15.1. Statistics on the Database Access Layer</h2></div></div></div><p>In order to have a better idea of the time spent into the database
    access layer, it cans be interesting to get some statistics on that part
    of the code, knowing that most of the time spent into eXo JCR is mainly
    the database access. This statistics will then allow you to identify
    without using any profiler what is anormally slow in this layer, which
    could help to fix the problem quickly.</p><p>In case you use
    <code class="envar">org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</code>
    or
    <code class="envar">org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</code>
    as <code class="envar">WorkspaceDataContainer</code>, you can get statistics on the
    time spent into the database access layer. The database access layer (in
    eXo JCR) is represented by the methods of the interface
    <code class="envar">org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</code>,
    so for all the methods defined in this interface, we can have the
    following figures:</p><div class="itemizedlist"><ul><li><p>The minimum time spent into the method.</p></li><li><p>The maximum time spent into the method.</p></li><li><p>The average time spent into the method.</p></li><li><p>The total amount of time spent into the method.</p></li><li><p>The total amount of times the method has been called.</p></li></ul></div><p>Those figures are also available globaly for all the methods which
    gives us the global behavior of this layer.</p><p>If you want to enable the statistics, you just need to set the JVM
    parameter called
    <span class="emphasis"><em>JDBCWorkspaceDataContainer.statistics.enabled</em></span> to
    <span class="emphasis"><em>true</em></span>. The corresponding CSV file is
    <span class="emphasis"><em>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</em></span>
    for more details about how the csv files are managed please refer to the
    section dedicated to the statistics manager.</p><p>The format of each column header is ${method-alias}-${metric-alias}.
    The metric alias are described in the statistics manager section.</p><div class="table"><a id="d0e2152"/><p class="title"><b>Table 15.1. Method Alias</b></p><div class="table-contents"><table summary="Method Alias" border="1"><colgroup><col/><col/></colgroup><tbody><tr><td>global</td><td>This is the alias for all the methods.</td></tr><tr><td>getItemDataById</td><td>This is the alias for the method
            <span class="emphasis"><em>getItemData(String identifier).</em></span></td></tr><tr><td>getItemDataByNodeDataNQPathEntry</td><td>This is the alias for the method
            <span class="emphasis"><em>getItemData(NodeData parentData, QPathEntry
            name).</em></span></td></tr><tr><td>getChildNodesData</td><td>This is the alias for the method
            <span class="emphasis"><em>getChildNodesData(NodeData parent).</em></span></td></tr><tr><td>getChildNodesCount</td><td>This is the alias for the method
            <span class="emphasis"><em>getChildNodesCount(NodeData parent).</em></span></td></tr><tr><td>getChildPropertiesData</td><td>This is the alias for the method
            <span class="emphasis"><em>getChildPropertiesData(NodeData
            parent).</em></span></td></tr><tr><td>listChildPropertiesData</td><td>This is the alias for the method
            <span class="emphasis"><em>listChildPropertiesData(NodeData
            parent).</em></span></td></tr><tr><td>getReferencesData</td><td>This is the alias for the method
            <span class="emphasis"><em>getReferencesData(String
            nodeIdentifier).</em></span></td></tr><tr><td>commit</td><td>This is the alias for the method
            <span class="emphasis"><em>commit().</em></span></td></tr><tr><td>addNodeData</td><td>This is the alias for the method <span class="emphasis"><em>add(NodeData
            data).</em></span></td></tr><tr><td>addPropertyData</td><td>This is the alias for the method <span class="emphasis"><em>add(PropertyData
            data).</em></span></td></tr><tr><td>updateNodeData</td><td>This is the alias for the method <span class="emphasis"><em>update(NodeData
            data).</em></span></td></tr><tr><td>updatePropertyData</td><td>This is the alias for the method
            <span class="emphasis"><em>update(PropertyData data).</em></span></td></tr><tr><td>deleteNodeData</td><td>This is the alias for the method <span class="emphasis"><em>delete(NodeData
            data).</em></span></td></tr><tr><td>deletePropertyData</td><td>This is the alias for the method
            <span class="emphasis"><em>delete(PropertyData data).</em></span></td></tr><tr><td>renameNodeData</td><td>This is the alias for the method <span class="emphasis"><em>rename(NodeData
            data).</em></span></td></tr><tr><td>rollback</td><td>This is the alias for the method
            <span class="emphasis"><em>rollback().</em></span></td></tr><tr><td>isOpened</td><td>This is the alias for the method
            <span class="emphasis"><em>isOpened().</em></span></td></tr><tr><td>close</td><td>This is the alias for the method
            <span class="emphasis"><em>close().</em></span></td></tr></tbody></table></div></div><br class="table-break"/></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="d0e2288"/>15.2. Statistics on the JCR API accesses</h2></div></div></div><p>In order to know exactly how your application uses eXo JCR, it cans
    be interesting to register all the JCR API accesses in order to easily
    create real life test scenario based on pure JCR calls and also to tune
    your eXo JCR to better fit your requirements.</p><p>In order to allow you to specify into the configuration which part
    of eXo JCR needs to be monitored whitout applying any changes in your code
    and/or building anything, we choosed to rely on the Load-time Weaving
    proposed by AspectJ.</p><p>To enable this feature, you will have to add in your classpath the
    following jar files:</p><div class="itemizedlist"><ul><li><p><span class="emphasis"><em>exo.jcr.component.statistics-X.Y.Z</em></span>.jar
        corresponding to your eXo JCR version that you can get from the jboss
        maven repository <a xmlns:xlink="http://www.w3.org/1999/xlink" href="???"><code class="uri">http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr.component.statistics</code></a>.</p></li><li><p>aspectjrt-1.6.8.jar that you can get from the main maven
        repository <a xmlns:xlink="http://www.w3.org/1999/xlink" href="???"><code class="uri">http://repo2.maven.org/maven2/org/aspectj/aspectjrt</code></a>.</p></li></ul></div><p>You will also need to get aspectjweaver-1.6.8.jar from the main
    maven repository <a xmlns:xlink="http://www.w3.org/1999/xlink" href="???">http://repo2.maven.org/maven2/org/aspectj/aspectjweaver</a>.
    At this stage, to enable the statistics on the JCR API accesses, you will
    need to add the JVM parameter
    <span class="emphasis"><em>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</em></span> to your
    command line, for more details please refer to <a xmlns:xlink="http://www.w3.org/1999/xlink" href="???">http://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html</a>.</p><p>By default, the configuration will collect statistcs on all the
    methods of the internal interfaces
    <span class="emphasis"><em>org.exoplatform.services.jcr.core.ExtendedSession</em></span> and
    <span class="emphasis"><em>org.exoplatform.services.jcr.core.ExtendedNode</em></span>, and
    the JCR API interface <span class="emphasis"><em>javax.jcr.Property</em></span>. To add
    and/or remove some interfaces to monitor, you have two configuration files
    to change that are bundled into the jar
    <span class="emphasis"><em>exo.jcr.component.statistics-X.Y.Z</em></span>.jar, which are
    <span class="emphasis"><em>conf/configuration.xml</em></span> and
    <span class="emphasis"><em>META-INF/aop.xml</em></span>.</p><p>The file content below is the content of
    <span class="emphasis"><em>conf/configuration.xml</em></span> that you will need to modify
    to add and/or remove the full qualified name of the interfaces to monitor,
    into the list of parameter values of the init param called
    <span class="emphasis"><em>targetInterfaces</em></span>.</p><pre class="programlisting">&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
 xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt;

 &lt;component&gt;
   &lt;type&gt;org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig&lt;/type&gt;
   &lt;init-params&gt;
     &lt;values-param&gt;
       &lt;name&gt;targetInterfaces&lt;/name&gt;
       &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedSession&lt;/value&gt;
       &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedNode&lt;/value&gt;
       &lt;value&gt;javax.jcr.Property&lt;/value&gt;
     &lt;/values-param&gt;
   &lt;/init-params&gt;
  &lt;/component&gt;
&lt;/configuration&gt;</pre><p>The file content below is the content of
    <span class="emphasis"><em>META-INF/aop.xml</em></span> that you will to need to modify to
    add and/or remove the full qualified name of the interfaces to monitor,
    into the expression filter of the pointcut called
    <span class="emphasis"><em>JCRAPIPointcut</em></span>. As you can see below, by default only
    JCR API calls from the exoplatform packages are took into account, don't
    hesistate to modify also this filter to add your own package names.</p><pre class="programlisting">&lt;aspectj&gt;
  &lt;aspects&gt;
    &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt;
      &lt;pointcut name="JCRAPIPointcut"
        expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;amp;&amp;amp; call(public * *(..))" /&gt;
    &lt;/concrete-aspect&gt;
  &lt;/aspects&gt;
  &lt;weaver options="-XnoInline"&gt;
    &lt;include within="org.exoplatform..*" /&gt;
  &lt;/weaver&gt;
&lt;/aspectj&gt; </pre><p>The corresponding CSV files are of type
    <span class="emphasis"><em>Statistics${interface-name}-${creation-timestamp}.csv</em></span>
    for more details about how the csv files are managed please refer to the
    section dedicated to the statistics manager.</p><p>The format of each column header is ${method-alias}-${metric-alias}.
    The method alias will be of type ${method-name}(list of parameter types
    separeted by ; to be compatible with the CSV format).</p><p>The metric alias are described in the statistics manager
    section.</p><p class="remark"><i><span class="remark">Please note that this feature will affect the performances of eXo
    JCR so it must be used with caution.</span></i></p></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="d0e2376"/>15.3. Statistics Manager</h2></div></div></div><p>The statistics manager manages all the statistics provided by eXo
    JCR, it is responsible of printing the data into the CSV files but also to
    expose the statistics through JMX and/or Rest.</p><p>The statistics manager will create all the CSV files for each
    category of statistics that it manages, the format of those files is
    <span class="emphasis"><em>Statistics${category-name}-${creation-timestamp}.csv</em></span>.
    Those files will be created into the user directory if it is possible
    otherwise it will create them into the temporary directory. The format of
    those files is <code class="envar">CSV</code> (i.e. Comma-Seperated Values), one new
    line will be added regularily (every 5 seconds by default) and one last
    line will be added at JVM exit. Each line, will be composed of the 5
    figures described below for each method and globaly for all the
    methods.</p><div class="table"><a id="d0e2390"/><p class="title"><b>Table 15.2. Metric Alias</b></p><div class="table-contents"><table summary="Metric Alias" border="1"><colgroup><col/><col/></colgroup><tbody><tr><td>Min</td><td>The minimum time spent into the method.</td></tr><tr><td>Max</td><td>The maximum time spent into the method.</td></tr><tr><td>Total</td><td>The total amount of time spent into the method.</td></tr><tr><td>Avg</td><td>The average time spent into the method.</td></tr><tr><td>Times</td><td>The total amount of times the method has been
              called.</td></tr></tbody></table></div></div><p><br class="table-break"/>You can disable the persistence of the statistics by setting the
    JVM parameter called
    <span class="emphasis"><em>JCRStatisticsManager.persistence.enabled</em></span> to
    <span class="emphasis"><em>false</em></span>, by default it is set to
    <span class="emphasis"><em>true</em></span>. You can aslo define the period of time between
    each record (i.e. line of data into the file) by setting the JVM parameter
    called <span class="emphasis"><em>JCRStatisticsManager.persistence.timeout</em></span> to
    your expected value expressed in milliseconds, by default it is set to
    <span class="emphasis"><em>5000</em></span>.</p><p>You can also access to the statistics thanks to JMX, the available
    methods are the following:</p><div class="table"><a id="d0e2439"/><p class="title"><b>Table 15.3. JMX Methods</b></p><div class="table-contents"><table summary="JMX Methods" border="1"><colgroup><col/><col/></colgroup><tbody><tr><td>getMin</td><td>Gives the minimum time spent into the method
              corresponding to the given category name and statistics name.
              The expected arguments are the name of the category of the
              statistics (e.g. JDBCStorageConnection) and the name of the
              expected method or global for the global value.</td></tr><tr><td>getMax</td><td>Gives the maximum time spent into the method
              corresponding to the given category name and statistics name.
              The expected arguments are the name of the category of the
              statistics (e.g. JDBCStorageConnection) and the name of the
              expected method or global for the global value.</td></tr><tr><td>getTotal</td><td>Gives the total amount of time spent into the method
              corresponding to the given category name and statistics name.
              The expected arguments are the name of the category of the
              statistics (e.g. JDBCStorageConnection) and the name of the
              expected method or global for the global value.</td></tr><tr><td>getAvg</td><td>Gives the average time spent into the method
              corresponding to the given category name and statistics name.
              The expected arguments are the name of the category of the
              statistics (e.g. JDBCStorageConnection) and the name of the
              expected method or global for the global value.</td></tr><tr><td>getTimes</td><td>Gives the total amount of times the method has been
              called corresponding to the given category name and statistics
              name. The expected arguments are the name of the category of the
              statistics (e.g. JDBCStorageConnection) and the name of the
              expected method or global for the global value.</td></tr><tr><td>reset</td><td>Reset the statistics for the given category name and
              statistics name. The expected arguments are the name of the
              category of the statistics (e.g. JDBCStorageConnection) and the
              name of the expected method or global for the global
              value.</td></tr><tr><td>resetAll</td><td>Reset all the statistics for the given category name. The
              expected argument is the name of the category of the statistics
              (e.g. JDBCStorageConnection).</td></tr></tbody></table></div></div><p><br class="table-break"/>The full name of the related MBean is
    <span class="emphasis"><em>exo:service=statistic, view=jcr</em></span>.</p></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="ch-transaction-manager.html"><strong>Prev</strong>Chapter 14. TransactionManagerLookup</a></li><li class="up"><a accesskey="u" href="#"><strong>Top of page</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Front page</strong></a></li><li class="next"><a accesskey="n" href="part-kernel.html"><strong>Next</strong>Part II. eXoKernel</a></li></ul></body></html>