An extension dedicated to measuring performances of eZ Publish websites
=======================================================================

This tool is meant to measure performances of eZ Publish sites.

Performance measurement is designed to be used in production.
It will work with ezdebug turned off, and tries to be lightweight not to slow
down your server too much because of the measurements. For the same reason by
default it does not store performance data into the database, but as part of
the existing Apache log.
The amount of performance data measured is fully configurable, as well as the
mechanism used to store it.

It doubles as profiling tool as well, since version 0.4.
This means having at your fingertips more detailed information that the standard
debug output, complete with drill-down capabilities and call graphs.

Note for the causal reader: profiling means measuring all php function calls
executed by the web page, and is extremely heavy. It should only be used in development,
not in production environments.


Requirements:
-------------
. eZP >= 4.6 or 5.X (when running the Legacy Stack only)
. apache webserver recommended
. optionally: either a piwik or ga account
. optionally: the xhprof profiler and graphviz
. optionally: the Monolog library and its dependencies

How it works: performance logging
---------------------------------

- by logging performance indicators (also known as KPI) - for every page view -
  Supported indicators are, so far:
  . total execution time
  . total memory usage
  . number of db queries
  . all existing accumulators (only when in debug mode)
  . number of times any existing "event" has fired
  . database access, cluster db access and imagemagick conversion time (only by usage of special connector classes)
  . custom indicators set by the developer using php code or template code
  . any data coming from $module_result (for eZ 5.x, this needs a piece of template code to be added to the pagelayout)

- the logging of the data can be directed to different media:
  . the Apache access log
  . the piwik web analytics engine
  . the google analytics engine
  . a separate log file (Apache-log format)
  . a separate log file (csv format)
  . the Monolog logging library
  . a Pinba server
  . an Odoscope server
  . a Stasd server
  and in the future possibly even more.

  Logging to the Apache access log is recommended for a number of reasons: by default
  apache logs are rotated, so you do not risk filling your disks with data, and
  there is less of an IO performance hit in logging there, as the log files are
  written anyway.

- to ease statistical usage of the perf data saved in the Apache log, a courtesy cronjob/
  command line script is provided: updateperfstats.
  It can be used in a 2-phase performance analysis scenario:
  Phase 1: enable and configure ezperformanceogger to log to Apache log or to a
           custom log file; execute load tests
  Phase 2: run php extension/ezperformancelogger/bin/php/updateperfstats.php to
           parse the Apache access log and produce a csv file; import that csv
           file in your preferred spreadsheet tool or database

  If you don't care so much about a very small performance loss, you can log
  performance data directly to a csv-formatted log file, and skip execution
  of the updateperfstats.php script.

NB: the extension does not provide a way to visualize the logged
data, you will need an external tool for that:
. for data streamed to the Apache log or a separate log file, a spreadsheet program which can import csv files
. for data streamed to piwik, ga, odoscope or statsd/grpahite, use the analytics tool web interface

Notes:
- measured script runtime is a bit shorter than reality, as we can not hook at the very beginning and end of php process execution
- measured time is rounded to milliseconds
- measured ram usage is rounded to 1000 bytes
- db queries executed can by default only be measured when debug output is turned on.
  We provide an alternative db-connector class, only for eZ 4.4-5.1 / mysqli, which can be
  used to measure detailed db information when debug output is turned off
  (see files site.ini and ezperformancelogger.ini for details)
- eZ pages which end in a redirection or terminate execution during the view will
  not log data by default. To force even those pages to be measured you will have
  to patch the index.php file and add the following line to it:
      eZExecution::addCleanupHandler( array( 'eZPerfLogger', 'cleanup' ) );
  A good candidate location is next to the existing eZExecution::addCleanupHandler call.

  For eZ 5.x this is in ezpkernelweb.php instead, around line 191;
  please note that in this case the measured data can be lower than expected,
  you should also patch ezpkernelweb::runCallback() to avoid measuring data
  via calls to eZPerfLogger::disable() and reenable()



How it works: profiling
-----------------------

- the XHProf PECL extension is required to get profiling information

- profiling is enabled at the beginning of page execution in config.php, and stops
  a little bit before page ends. As such it is not 100% accurate

- profiling information is saved in files in var/log/xhprof

- a link to see detailed profiling information is added to the debug output at
  the bottom of the page (via javascript)

- all profiling data is stored, and can be viewed later. It is accessible from
  the Setup tab in the Admin Interface

- profiling can be enabled/disabled independently of performance logging, but when
  it is enabled any memory or execution time numbers logged will be useless

- for more info on XHProf, Google is your friend

Notes:
- profiling info is not clustered. It will only be available on the webserver where
  it was generated