cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From br...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/concepts profiler.xml book.xml
Date Mon, 24 Mar 2003 17:14:32 GMT
bruno       2003/03/24 09:14:31

  Modified:    src/documentation/xdocs/userdocs/concepts book.xml
  Added:       src/documentation/xdocs/userdocs/concepts profiler.xml
  Log:
  Added new document describing how to use the cocoon profiler.
  
  Revision  Changes    Path
  1.2       +1 -0      cocoon-2.1/src/documentation/xdocs/userdocs/concepts/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/concepts/book.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- book.xml	9 Mar 2003 00:08:17 -0000	1.1
  +++ book.xml	24 Mar 2003 17:14:31 -0000	1.2
  @@ -26,6 +26,7 @@
       <menu-item label="XML Validation" href="validation.html"/>
       <menu-item label="Databases" href="databases.html"/>
       <menu-item label="Modules" href="modules.html"/>
  +    <menu-item label="Profiler" href="profiler.html"/>
     </menu>
   
   </book>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/concepts/profiler.xml
  
  Index: profiler.xml
  ===================================================================
  <?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.xsl"/>
      <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>
  
  
  

Mime
View raw message