non-releases/trunk_before_flattening/src/documentation/src/content/xdocs/c21-profiler/content_en.html - cocoon - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Cocoon Profiler</title>
 <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
 <meta content="Bruno Dumon" name="DC.Creator">
 </head>
 <body>

 <h1>Profiler Overview</h1>

 <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>


 <h1>Usage</h1>

 <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>

 <h2>Change pipeline implementation</h2>
 <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>
 <pre class="code">&lt;map:pipes default="caching"&gt;
   [...]

   &lt;!-- The following two can be used for profiling:--&gt;
   &lt;map:pipe name="profile-caching"
     src="org.apache.cocoon.components.profiler.ProfilingCachingProcessingPipeline"/&gt;
   &lt;map:pipe name="profile-noncaching"
     src="org.apache.cocoon.components.profiler.ProfilingNonCachingProcessingPipeline"/&gt;
 &lt;/map:pipes&gt;</pre>
 <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>

 <h2>Add pipelines to generate the profiler information</h2>
 <div class="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.</div>
 <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>
 <pre class="code">&lt;map:generator label="content,data" logger="sitemap.generator.profiler" name="profiler"
     src="org.apache.cocoon.generation.ProfilerGenerator"/&gt;</pre>
 <p>Now add the following two matchers in an appropriate place in your sitemap:</p>
 <pre class="code">&lt;map:match pattern="profile.html"&gt;
   &lt;map:generate type="profiler"/&gt;
   &lt;map:transform src="profile2html.xsl"&gt;
     &lt;map:parameter name="use-request-parameters" value="true"/&gt;
   &lt;/map:transform&gt;
   &lt;map:serialize type="html"/&gt;
 &lt;/map:match&gt;

 &lt;map:match pattern="profile.xml"&gt;
   &lt;map:generate type="profiler"/&gt;
   &lt;map:serialize type="xml"/&gt;
 &lt;/map:match&gt;</pre>
 <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>
 <pre class="code">&lt;map:views&gt;
   &lt;map:view name="pretty-content" from-label="data"&gt;
     &lt;map:transform src="simple-xml2html.xslt"/&gt;
     &lt;map:serialize type="html"/&gt;
   &lt;/map:view&gt;
 &lt;/map:views&gt;</pre>
 <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>


 <h1>Notes</h1>

 <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>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title>Cocoon Profiler</title>
	<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
	<meta content="Bruno Dumon" name="DC.Creator">
	</head>
	<body>

	<h1>Profiler Overview</h1>

	<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>


	<h1>Usage</h1>

	<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>

	<h2>Change pipeline implementation</h2>
	<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>
	<pre class="code"><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></pre>
	<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>

	<h2>Add pipelines to generate the profiler information</h2>
	<div class="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.</div>
	<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>
	<pre class="code"><map:generator label="content,data" logger="sitemap.generator.profiler" name="profiler"
	src="org.apache.cocoon.generation.ProfilerGenerator"/></pre>
	<p>Now add the following two matchers in an appropriate place in your sitemap:</p>
	<pre class="code"><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></pre>
	<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>
	<pre class="code"><map:views>
	<map:view name="pretty-content" from-label="data">
	<map:transform src="simple-xml2html.xslt"/>
	<map:serialize type="html"/>
	</map:view>
	</map:views></pre>
	<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>


	<h1>Notes</h1>

	<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>


	</body>
	</html>