| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>Cocoon Profiler</title> |
| <version>1</version> |
| <type>Overview document</type> |
| <authors> |
| <person name="Bruno Dumon" email="bruno@apache.org"/> |
| </authors> |
| </header> |
| <body> |
| <s1 title="Profiler Overview"> |
| <p>The Cocoon Profiler has a double goal:</p> |
| <ul> |
| <li>it shows how much time is spent in each step of the SAX pipeline. |
| Because of the nature of SAX, this information is difficult or |
| impossible to obtain using general-purpose Java profilers. |
| Additionally, it shows the time spent in the setup() method of each |
| component of the pipeline (sometimes setup takes more time than the |
| actual processing!).</li> |
| <li>it allows to take a look at the XML produced in each step of a |
| pipeline. You can use this to get insight in how pipelines work or to |
| see what a particular transformer actually does. It is much easier |
| and comfortable than fuzzing around with the LogTransformer.</li> |
| </ul> |
| |
| <p>The profiler does not show the time spent in components during |
| pipeline setup. These include selectors and matchers, but most |
| importantly, actions. Since Actions are used to execute all kind of |
| logic such as communication with databases or EJB's, they can take up |
| quite some time. Use a general purpose Java profiling tool to analyze |
| them.</p> |
| |
| <p>The Cocoon samples include a demonstration of the profiler. It can be |
| found below "Block samples".</p> |
| </s1> |
| <s1 title="Usage"> |
| <p>To use the profiler, two things need to be done:</p> |
| <ul> |
| <li>Change the pipeline implementation</li> |
| <li>Add pipelines to generate the profiler information</li> |
| </ul> |
| <s2 title="Change pipeline implementation"> |
| <p>First, check that the profiling pipeline implementations (caching and/or |
| noncaching) are declared in the map:components section of the sitemap. |
| Here is an example:</p> |
| |
| <source><![CDATA[<map:pipes default="caching"> |
| [...] |
| |
| <!-- The following two can be used for profiling:--> |
| <map:pipe name="profile-caching" |
| src="org.apache.cocoon.components.profiler.ProfilingCachingProcessingPipeline"/> |
| <map:pipe name="profile-noncaching" |
| src="org.apache.cocoon.components.profiler.ProfilingNonCachingProcessingPipeline"/> |
| </map:pipes>]]></source> |
| |
| <p>You can now turn on the profiling in two ways:</p> |
| <ul> |
| <li>Change the default pipeline implementation by changing the value of the default |
| attribute on the map:pipes element.</li> |
| <li>Change the pipeline implementation of a specific map:pipeline by |
| adding a type attribute to it with as value "profile-caching" or |
| "profiling-noncaching".</li> |
| </ul> |
| </s2> |
| <s2 title="Add pipelines to generate the profiler information"> |
| <note>Instead of following the instructions below, you could also reuse |
| the profiler demonstration from the Cocoon samples as-is, and mount |
| it into your own application.</note> |
| |
| <p>The information gathered by the profiler can be retrieved using the |
| ProfilerGenerator. Make sure the profiler generator is declared |
| inside the map:generators element in the sitemap, as follows:</p> |
| <source><![CDATA[<map:generator label="content,data" logger="sitemap.generator.profiler" name="profiler" |
| src="org.apache.cocoon.generation.ProfilerGenerator"/>]]></source> |
| <p>Now add the following two matchers in an appropriate place in your sitemap:</p> |
| <source><![CDATA[<map:match pattern="profile.html"> |
| <map:generate type="profiler"/> |
| <map:transform src="profile2html.xsl"> |
| <map:parameter name="use-request-parameters" value="true"/> |
| </map:transform> |
| <map:serialize type="html"/> |
| </map:match> |
| |
| <map:match pattern="profile.xml"> |
| <map:generate type="profiler"/> |
| <map:serialize type="xml"/> |
| </map:match>]]></source> |
| |
| <p>Make sure the profile2html.xsl stylesheet is available, you can |
| find it in te Cocoon distribution.</p> |
| |
| <p>You also need the pretty-content view (which is included in the |
| default Cocoon sitemap). It can be added in the map:views section of |
| the sitemap as follows:</p> |
| |
| <source><![CDATA[<map:views> |
| <map:view name="pretty-content" from-label="data"> |
| <map:transform src="simple-xml2html.xslt"/> |
| <map:serialize type="html"/> |
| </map:view> |
| </map:views>]]></source> |
| |
| <p>Again, make sure the simple-xml2html.xsl stylesheet is available, it |
| can also be found in the Cocoon distribution.</p> |
| |
| <p>Now you are ready to use the profiler. First make a series of requests |
| on the pages you want to profile, then go look at the profiler results |
| by requesting the profile.html page.</p> |
| </s2> |
| </s1> |
| <s1 title="Notes"> |
| <ul> |
| <li>the profiler is contained in a seperate Cocoon block. Unless you |
| deactivated it, it is included in the standard build.</li> |
| <li>if you are streaming very large documents through the pipeline, the |
| profiler will use a lot of memory since it buffers the data in |
| between pipeline components.</li> |
| <li>profiling has a very negative impact on performance and memory |
| usage, since it buffers all data between pipeline components. Only |
| activate it when required, and never activate it on production |
| systems.</li> |
| <li>when using the profile-caching pipeline implementation the XML |
| generated by components will only be available on non-cached |
| executions.</li> |
| </ul> |
| </s1> |
| </body> |
| </document> |