================
Benchmark How-to
================

:Revision: $Id: howto-benchmark.txt 30254 2005-12-04 01:49:55Z dkuhlman $

.. sectnum::    :depth: 4
.. contents::   :depth: 4


Setup Benchmarking
==================

cpsinstall setup an external method named Benchmarktimer into your
cps folder::

	id:BenchmarkTimer
	Title:BenchmarkTimer
	module name:CPSDefault.benchmarktimer
	function name:BenchmarkTimerInstance

You have to add the following line in your Zope server start
script::

    BENCHMARKTIMER_LEVEL=-2
    export BENCHMARKTIMER_LEVEL

Under Zope 2.8 the previous export should be set in your ./bin/zopectl or
you can test it using runzope::

    BENCHMARKTIMER_LEVEL=-2 ./bin/runzope


To Profile a ZPT
=================

::

    <tal:block define="BMT python:here.Benchmarktimer('my_zpt');">

    <span tal:replace="BMT/start" />
    ...
    <span tal:replace="python:BMT.setMarker('mark1')" />
    ...
    <span tal:replace="python:BMT.setMarker('mark2')" />
    ...
    <span tal:replace="BMT/stop" />

Display the above BMT profiling result::

    <span tal:replace="structure BMT/getProfiling" />

If you want to display other profiler result coming from python
script::

    <span tal:replace="structure request/other/bench_mark_profiler|nothing" />

    </tal:block>

Note that during the development of CPS the default
main_template.pt defines a default benchmark environment.


To Profile a Python Script
==========================

Add this::

    bmt = context.Benchmarktimer('foo', level=-3)
    bmt.start()

Do something::

    bmt.stop()
    bmt.saveProfile(context.REQUEST) # the result will be displayed in
                                     # the main template

or::

    return bmt.getProfiling() # return the result


Bench Marking
=============

Bench marking here is just running many times the result of a URL.

To benchmark::

    http://server/foo/bar

Use::

    http://server/bench?foo/bar

Note that 'bar' can be a ZPT, a Python script, or an object.


Recommendation
==============

Always use bmt or BMT when using BenchmarkTimer. It will be easier
to remove this tool when switching to production.

