cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From reinh...@apache.org
Subject svn commit: r806352 - in /cocoon/cocoon3/trunk/cocoon-docs: ./ src/docbkx/reference/ src/docbkx/reference/graphics/
Date Thu, 20 Aug 2009 20:50:37 GMT
Author: reinhard
Date: Thu Aug 20 20:50:36 2009
New Revision: 806352

URL: http://svn.apache.org/viewvc?rev=806352&view=rev
Log:
COCOON3-40 Cocoon Profiling: Documentation

Added:
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profilingGraph.jpg   (with
props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_argument.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_component.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_exception.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_invocation.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_node.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_profiler.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_property.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_return.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_servlet.jpg
  (with props)
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_sitemap.jpg
  (with props)
Modified:
    cocoon/cocoon3/trunk/cocoon-docs/pom.xml
    cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/web-applications.xml

Modified: cocoon/cocoon3/trunk/cocoon-docs/pom.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/pom.xml?rev=806352&r1=806351&r2=806352&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/pom.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/pom.xml Thu Aug 20 20:50:36 2009
@@ -94,6 +94,11 @@
                     <include name="**/*.jpg" />
                   </fileset>
                 </copy>
+                <copy todir="${basedir}/target/site/reference/html-single/graphics">
+                  <fileset dir="${basedir}/src/docbkx/reference/graphics">
+                    <include name="**/*.*" />
+                  </fileset>
+                </copy>                
                 <move file="target/site/reference/pdf/index.pdf"
                   tofile="target/site/reference/pdf/cocoon3-reference.pdf" failonerror="false"
/>
               </postProcess>
@@ -122,6 +127,11 @@
                     <include name="**/*.jpg" />
                   </fileset>
                 </copy>
+                <copy todir="${basedir}/target/site/reference/html/graphics">
+                  <fileset dir="${basedir}/src/docbkx/reference/graphics">
+                    <include name="**" />
+                  </fileset>
+                </copy>                
               </postProcess>
             </configuration>
             <phase>pre-site</phase>

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profilingGraph.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profilingGraph.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profilingGraph.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_argument.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_argument.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_argument.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_component.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_component.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_component.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_exception.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_exception.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_exception.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_invocation.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_invocation.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_invocation.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_node.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_node.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_node.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_profiler.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_profiler.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_profiler.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_property.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_property.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_property.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_return.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_return.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_return.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_servlet.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_servlet.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_servlet.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_sitemap.jpg
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_sitemap.jpg?rev=806352&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/graphics/profiling_firebug_sitemap.jpg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/web-applications.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/web-applications.xml?rev=806352&r1=806351&r2=806352&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/web-applications.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/web-applications.xml Thu Aug 20
20:50:36 2009
@@ -310,6 +310,260 @@
     <para>TBW: Integeration tests</para>
   </section>
 
+  <section id="webapps.profiling">
+    <title>Profiling support</title>
+    <para>
+      A cocoon request goes through many components; while performing a Cocoon request, servlets,
sitemaps and pipeline 
+      components are being executed.  It is also quite common that Cocoon requests are cascaded
which makes it sometimes 
+      difficult to understand what exactly was happening. Cocoon Profiling enables you to
profile any request to your website.</para>
+    <section>
+      <title>Module configuration</title>
+      <para>
+        In order to use cocoon-profiling, you simply have to include the <literal>cocoon-profiling
jar</literal> in your classpath. 
+        Cocoon-profiling uses Spring AOP, so no further configuration is needed.
+      </para>
+    </section>
+    <section>
+      <title>Using Cocoon Profiling</title>
+      <para>
+        Cocoon-profiling provides several generators for xml and graphical output, which
is used by the Firebug plugin. 
+        However, you can directly access the data using
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>yourdomain.com/controller/profiling/{id}</literal>  for
the xml file (xml schema see 
+              <literal>profilingSchema.xsd</literal> in cocoon-profiling)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>yourdomain.com/controller/profiling/{id}.png</literal>
for the graphical representation (example see below)
+            </para>
+          </listitem>
+        </itemizedlist>
+        where {id} is the id of the request. This id (<literal>X-Cocoon-Profiling-ID</literal>)
can be found in the header of the 
+        original request.
+      </para>
+      <para>
+        This is an example for the graphical representation:
+      </para>
+      <para>
+        <mediaobject>
+          <imageobject role="html">
+            <imagedata fileref="graphics/profilingGraph.jpg" contentwidth="75%" format="JPG"/>
+          </imageobject>
+          <imageobject role="fo">
+            <imagedata fileref="../src/docbkx/reference/graphics/profilingGraph.jpg" format="JPG"/>
+          </imageobject>        
+        </mediaobject>
+      </para>
+      <section>
+        <title>How can I enable/disable cocoon-profiling on the fly?</title>
+        <para>
+          Cocoon-profiling is enabled per default. If you just want to use it, you can skip
this section. 
+        </para>
+        <para>
+          If you want to start or stop profiling while the server is running, you can use
the management bean provided by cocoon-profiling. 
+          Cocoon-monitoring automatically exposes this MBean; just make sure that cocoon-monitoring
is in your classpath. You can then 
+          connect to the server process using jconsole and call the "start" and "stop" method
of the org.apache.cocoon.profiling MBean.
+        </para>
+        <para>
+          Keep in mind that cocoon-profiling uses Spring AOP to intercept method calls, which
cannot be enabled or disabled at runtime. 
+          Therefore, a disabled cocoon-profiling still affects the performance (at least
a little bit). Only removing cocoon-profiling 
+          from the classpath and restarting the server guarantees maximum performance.
+        </para>
+      </section>
+      <section>
+        <title>I need cocoon-profiling to profile my custom cocoon component, how can
I do that?</title>
+        <para>
+          Generally, you don't have to change anything. Cocoon-profiling uses Spring AOP
to profile all cocoon components and servlets 
+          as well as any subclass or cocoon interface implementation.
+        </para>
+        <para>
+          Advanced users might want to add their own Profiler class to cocoon-profiling if
they have a specific component with 
+          specific parameters or other bits of data they want cocoon-profiling to collect.
+        </para>
+      </section>
+    </section>
+    <section>
+      <title>Using Firebug with Cocoon-profiling</title>
+      <para>
+        Getting the Firebug Plugin able to work is really easy. You'll need to install Firebug
1.4X from 
+        <literal>http://getfirebug.com/releases/firebug/1.4X</literal> and then
install the Firebug .xpi from 
+        cocoon-profiling-firebug (opening it with Firefox should suffice). The generate the
xpi from the sources, 
+        simply switch to the cocoon-profiling-firebug folder and type <literal>mvn
install</literal>. This will 
+        automatically build a new xpi. After installing the plugins, you should have a little
bug on the bottom 
+        right corner of your Firefox. Clicking will open it, then you can navigate to the
net-panel (you might want 
+        to be sure its activated) and there open up a request (you might need to refresh).
In the request, there 
+        should be a tab called "Cocoon 3 Profiling", if you click it, and the Profiling Service
works, you should 
+        now see the generated profiling data.
+      </para>
+      <para>
+        The data itself is presented in two textboxes. The left one is the tree which resembles
the .xml that the 
+        profiling-component generates, the right one displays the elements, properties, return-values
and the profiler
+        of a given (= selected) row in the left tree. You can navigate through the left tree,
and based on which row 
+        you currently have selected, the right textbox will display the names and values.
To add some visual help, pictures 
+        are being displayed, based on which kind of element is displayed.
+      </para>
+      <para>
+        The underline is:
+      </para>
+      <para>
+        <table id="webapps.profiling.firebug.table" pgwide="0">
+          <title>Icons</title>
+          <tgroup cols="3">
+            <colspec colname="c1"/>
+            <colspec colname="c2"/>
+            <colspec colname="c3"/>
+            <tbody>
+              <row>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_argument.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_argument.jpg"
format="JPG"/>
+                     </imageobject>                         
+                    <caption>Argument</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_component.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_component.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Component</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_exception.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_exception.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Exception</caption>
+                  </mediaobject>
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_invocation.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_invocation.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Invocation</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_node.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_node.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Node</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_profiler.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_profiler.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Profiler</caption>
+                  </mediaobject>
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_property.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_property.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Property</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_return.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_return.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Return-value</caption>
+                  </mediaobject>
+                </entry>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_servlet.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_servlet.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Servlet</caption>
+                  </mediaobject>
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  <mediaobject>
+                    <imageobject role="html">
+                      <imagedata fileref="graphics/profiling_firebug_sitemap.jpg" format="JPG"/>
+                    </imageobject>
+                    <imageobject role="fo">
+                      <imagedata fileref="../src/docbkx/reference/graphics/profiling_firebug_sitemap.jpg"
format="JPG"/>
+                     </imageobject>                       
+                    <caption>Sitemap</caption>
+                  </mediaobject>
+                </entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+      </para>
+      <para>
+        You also have two options which can change what you'll be able to see in the Firebug
Plugin. 
+        These are located on the net Tab Option Panel, which is a little triangle. The options
are marked {c3p} 
+        and allow you to Show / Hide the Sitemap and to change if the invocations element
of the tree is 
+        closed or opened. These changes will require a reload, 
+        either by reloading your browser, or by clicking the "Reload"-Button in the Profiling
Panel.
+      </para>
+      <para>
+        The other button on the panel will open a new tab in your Firefox in which a graphical
outline will 
+        be shown which lists your components and the execution time of each of these components.
Be aware, 
+        though, that the first profiling cycle will present you a kind of wrong picture (it
takes a lot longer), 
+        because of the java-intern class-loading and other administrative stuff. You'll need
to reload the request, 
+        not the picture, to change this.
+      </para>
+      <section>
+        <title>Customizing your Firebug Plugin</title>
+        <para>
+          To customize your Firebug Plugin, go to the plugin folder in your Firefox, select
the Profiling plugin, 
+          then navigate to <literal>chrome\skin\classic\cocoon3profiling.css</literal>.
In this css, you can change 
+          the heigth and width of the trees and of their columns. Simply navigate to the
element you want to change, 
+          and change the value in there.
+        </para>
+      </section>
+    </section>
+  </section>
+
   <section id="webapps.monitoring">
     <title>Monitoring support</title>
     <para>



Mime
View raw message