bruno 2003/03/24 09:14:59
Modified: src/documentation/xdocs/userdocs/generators
profile-generator.xml
Log:
Updated to reflect the current profiler generator implementation.
I haven't bothered to update the DTD.
Revision Changes Path
1.2 +95 -173
cocoon-2.1/src/documentation/xdocs/userdocs/generators/profile-generator.xml
Index: profile-generator.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/generators/profile-generator.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- profile-generator.xml 9 Mar 2003 00:08:19 -0000 1.1
+++ profile-generator.xml 24 Mar 2003 17:14:59 -0000 1.2
@@ -7,6 +7,7 @@
<version>0.9</version>
<type>Technical document</type>
<authors>
+ <person name="Bruno Dumon" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the profile generator of
@@ -14,188 +15,109 @@
</header>
<body>
<s1 title="Profile Generator">
- <p>
- The profile generator creates xml from the current profiler
-measurement
- results of cocoon.
- </p>
- <p>
- The information is surrounded by the root element
-<code>profilerinfo</code>
- and grouped with the elements <code>pipeline</code>,
- <code>average</code>, <code>result</code> and
-<code>element</code>.
- </p>
- <p>
- The <code>profilerinfo</code> element has the attribute
-<code>date</code>.
- The <code>pipeline</code> element has the attributes
- <code>uri</code>, <code>count</code> and <code>time</code>.
- The <code>average</code> element has the attribute
- <code>time</code>.
- The <code>element</code> element has the attributes
- <code>role</code>, <code>source</code> and <code>time</code>.
- </p>
- <p>
- A <code>pipeline</code> summarizes profile information of a
-pipeline
- as specified in the <code>sitemap</code>.
- Each <code>pipeline</code> element consists of
- an <code>average</code>, and a <code>result</code> element.
- The <code>average</code> element describes the average time
-values,
- whereas the <code>result</code> element describes each pipeline
-processing.
- </p>
- <p>
- The <code>element</code> element describes the timing values
-for each stage of
- the pipeline processing.
- </p>
- <p>
- All elements have the namespace
- <code>http://apache.org/cocoon/profiler/1.0</code>.
- </p>
+ <p>The profile generator creates xml from the current profiler
+ measurement results of cocoon.</p>
+ <p>If you just want to use the Cocoon profiler, look at <link
+ href="../concepts/profiler.html">this document</link>.</p>
<ul>
<li>Name : profile</li>
- <li>Class:
-org.apache.cocoon.components.profiler.ProfilerGenerator</li>
- <li>Cacheable: no.</li>
+ <li>Class: org.apache.cocoon.components.profiler.ProfilerGenerator</li>
+ <li>Cacheable: no</li>
</ul>
- <s2 title="Configuraton of cocoon.xconf">
- <p>Edit <code>cocoon.xconf</code>
- </p>
-<source><![CDATA[
-...
-<event-pipeline class="org.apache.cocoon.components.profiler.\
- ProfilingNonCachingEventPipeline"/>
-<sax-connector class="org.apache.cocoon.components.profiler.\
- ProfilingSAXConnector"/>
-...
-<profiler/>
-]]></source>
- </s2>
- <s2 title="Configuration sitemap.xmap">
- <p>Edit <code>sitemap.xmap</code>
- </p>
-<source><![CDATA[
- <map:generators default="file">
- ...
- <map:generator name="profile"
- src="org.apache.cocoon.components.profiler.ProfilerGenerator"
-label="content"/>
- </map:generators> ...
-
- <map:match pattern="profile">
- <map:generate type="profile"/>
- <map:transform type="xslt" src="stylesheets/system/profile2html.xsl"/>
- <map:serialize/>
- </map:match>
-]]></source>
- </s2>
- <p>
- You may try <code>http://localhost/cocoon/profile</code>
- several times.
- </p>
- </s1>
- <s1 title="Configuration">
- <p>The following parameter can be specified in the pipeline for
- the generate command:
- </p>
- <ul>
- <li>
- sort (optional) : Sets how Profile Generator sorts
- pipeline elements. You may set <code>sort</code> to
-<code>uri</code>
- to sort <code>pipeline</code> element by its <code>uri</code>
-attribute,
- setting <code>sort</code> to time sorts
- <code>pipeline</code> elements by its <code>time</code>
-attribute,
- finally setting <code>sort</code> to count sorts
-<code>pipeline</code> elements
- by its <code>count</code> attribute.
- </li>
- </ul>
- </s1>
- <s1 title="DTD">
- <p>XML generated by status generator uses namespace
- <code>http://apache.org/cocoon/status/2.0</code>. The DTD of XML
- generated by status generator:
- </p>
-<source><![CDATA[
-<!ELEMENT profilerinfo (pipeline)*>
-<!ATTLIST profilerinfo
- date CDATA #IMPLIED
->
-
-<!ELEMENT pipeline (average, result)*>
-<!ATTLIST pipeline
- uri CDATA #REQUIRED
- count CDATA #REQUIRED
- time CDATA #REQUIRED
->
-<!ELEMENT average (element)*>
-<!ATTLIST average
- time CDATA #REQUIRED
->
-
-<!ELEMENT result (element)*>
-<!ATTLIST result
- time CDATA #REQUIRED
->
-
-<!ELEMENT element EMPTY>
-<!ATTLIST element
- role CDATA #REQUIRED
- source CDATA #IMPLIED
- time CDATA #REQUIRED
->
-
-]]></source>
- </s1>
- <s1 title="Example">
- <p>The profile generator may output information:
- </p>
-<source><![CDATA[
-<profilerinfo xmlns="http://apache.org/cocoon/profiler/1.0";
- date="01.09.2001 21:50:00">
- <pipeline uri="welcome" count="1" time="481">
- <average time="481">
- <element role="file" source="docs/samples/samples.xml"
-time="250"/>
- <element role="xslt" source="stylesheets/simple-samples2html.xsl"
-time="171"/>
- <element role="org.apache.cocoon.serialization.HTMLSerializer"
-time="60"/>
+
+ <p>When no parameters are specified, the profiler generator will simply
+ generate all available information. Here is some example output:</p>
+
+ <source><![CDATA[<profilerinfo date="Mar 24, 2003 5:10:56 PM"
xmlns="http://apache.org/cocoon/profiler/1.0";>
+ <pipeline count="2" key="4704447257427244431" processingTime="378"
uri="caching-testsite.html">
+ <average time="189">
+ <component offset="0" role="file" source="test.xml" time="1"/>
+ <component offset="1" role="xslt" source="test2page.xsl" time="58"/>
+ <component offset="2" role="xslt" source="page2html.xsl" time="115"/>
+ <component offset="3" role="html" time="2"/>
</average>
- <result time="481">
- <element role="file" source="docs/samples/samples.xml"
-time="250"/>
- <element role="xslt" source="stylesheets/simple-samples2html.xsl"
-time="171"/>
- <element role="org.apache.cocoon.serialization.HTMLSerializer"
-time="60"/>
+ <result index="0" time="128">
+ <component index="0" processing="0" role="file" setup="0"
+ source="test.xml" time="0"/>
+ <component index="1" processing="0" role="xslt" setup="59"
+ source="test2page.xsl" time="59"/>
+ <component index="2" processing="0" role="xslt" setup="65"
+ source="page2html.xsl" time="65"/>
+ <component index="3" processing="0" role="html" setup="0" time="0"/>
+ </result>
+ <result index="1" time="250">
+ <component index="0" processing="1" role="file" setup="1"
+ source="test.xml" time="2"/>
+ <component index="1" processing="1" role="xslt" setup="56"
+ source="test2page.xsl" time="57"/>
+ <component index="2" processing="21" role="xslt" setup="145"
+ source="page2html.xsl" time="166"/>
+ <component index="3" processing="5" role="html" setup="0" time="5"/>
</result>
</pipeline>
- <pipeline uri="profile" count="1" time="3355">
- <average time="3355">
- <element role="profile" time="2964"/>
- <element role="xslt" source="stylesheets/system/profile2html.xsl"
-time="180"/>
- <element role="org.apache.cocoon.serialization.HTMLSerializer"
-time="211"/>
+ <pipeline count="1" key="-1812911851413592444" processingTime="190"
uri="noncaching-testsite.html">
+ <average time="190">
+ <component offset="0" role="file" source="test.xml" time="1"/>
+ <component offset="1" role="xslt" source="test2page.xsl" time="86"/>
+ <component offset="2" role="xslt" source="page2html.xsl" time="70"/>
+ <component offset="3" role="html" time="19"/>
</average>
- <result time="3355">
- <element role="profile" time="2964"/>
- <element role="xslt" source="stylesheets/system/profile2html.xsl"
-time="180"/>
- <element role="org.apache.cocoon.serialization.HTMLSerializer"
-time="211"/>
+ <result index="0" time="190">
+ <component index="0" processing="1" role="file" setup="0"
+ source="test.xml" time="1"/>
+ <component index="1" processing="3" role="xslt" setup="83"
+ source="test2page.xsl" time="86"/>
+ <component index="2" processing="7" role="xslt" setup="63"
+ source="page2html.xsl" time="70"/>
+ <component index="3" processing="19" role="html" setup="0" time="19"/>
</result>
</pipeline>
-</profilerinfo>
-]]></source>
+</profilerinfo>]]></source>
+
+ <p>The output consists of a <code>profilerinfo</code> element containing
+ a number of <code>pipeline</code> elements. Each pipeline is
+ identified by a key. The pipeline element contains one
+ <code>average</code> element (containing the average results) and one
+ or more <code>result</code> elements for the individual results
+ (by default only the last 10 results are remembered). Each result element
+ contains a number of <code>component</code> elements, one for each
+ component (generator, transformer, serializer) in the pipeline.</p>
+
+ <p>All elements have the namespace
+ <code>http://apache.org/cocoon/profiler/1.0</code>.</p>
+
+ <p>On the component element, there are three attributes indicating
timings:</p>
+ <dl>
+ <dt>setup</dt>
+ <dd>time spent in the component's setup method</dd>
+ <dt>processing</dt>
+ <dd>time spent processing the SAX events</dd>
+ <dt>time</dt>
+ <dd>sum of the processing and setup times</dd>
+ </dl>
+
+ <p>The output of the profiler generator can be tuned using the following
+ request parameters:</p>
+
+ <dl>
+ <dt>key</dt>
+ <dd>limit the output to the pipeline with this key</dd>
+ <dt>result</dt>
+ <dd>to be used in combination with key, causes only the result with
+ this index to be included. In this case some additional information
+ about the environment (request parameters and session attributes)
+ will be returned.</dd>
+ <dt>component</dt>
+ <dd>to be used in combination with key and result. When this parameter
+ is specified, the XML that was generated by the component with this
+ index will be included in the output (as child of the specified
+ component element).</dd>
+ <dt>fragmentonly</dt>
+ <dd>to be used in combination with key, result and component. If this
+ parameter is true, only the XML that was generated by the specified
+ component will be returned, without additional profiler information
+ around it.</dd>
+ </dl>
</s1>
</body>
</document>
