README

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 running in pure-legacy-stack mode (NB: when running eZ5 in anything else but Legacy-Stack-only mode, you will need to install eZPerformanceLoggerBundle)
apache webserver recommended
optionally: either a piwik or ga account
optionally: the xhprof profiler and graphviz
optionally: the Monolog library and its dependencies

Installation:

See the INSTALL.md doc

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 eZ4 accumulators (only when in debug mode)
- number of times any existing eZ4 "event" has fired
- eZ4 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 Statsd server
- http response headers (useful for Nginx logs) 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/graphite, 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.3 / 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: eZPerfLogger::registerShutdownPerfLogger(); A good candidate location is next to the existing eZExecution::addCleanupHandler call.

For eZ 5.x in Legacy-Stack-Only mode, 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().

For eZ 5.x in any other mode, you do not need to do anything - it just works and logs redirecting pages.

If you do now want to hack the kernel and are using the customized db connector, you just need instead to set AlwaysRegisterShutdownPerfLogger=enabled in ezperformacelogger.ini

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 numbers logged for memory or execution time 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

Similar tools

There are many Application Performance Management solutions out there, which can do a lot more of this extension. A very good (but not entirely free) APM tool is NewRelic.

For application profiling, besides XHProf and XDebug, there is (but not entirely free) Blackfire.io.

gggeek / ezperformancelogger

Maintainers

Details