You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by re...@apache.org on 2009/08/20 22:50:37 UTC
svn commit: r806352 - in /cocoon/cocoon3/trunk/cocoon-docs: ./
src/docbkx/reference/ src/docbkx/reference/graphics/
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>