Update docs for upcoming version 0.13

INSTALL_5x

@@ -0,0 +1,24 @@
+Installation instructions for eZ Publish 5.x
+============================================
+
+The following instructions apply when you are NOT running an eZP 5.x installation in "pure legacy mode". If this is the
+case, use the installation instructions for version 4.
+Pure-legacy mode is when the document root of your webserver points to the /ezpublish_legacy directory instead of the /web
+one.
+If you are using a "legacy siteaccess" by having set 'legacy_mode' in yml configuration, do follow these instructions.
+
+
+1. Install the eZPerformanceLoggerBundle, using composer
+
+2. Follow the installation and configuration instructions of this extension for eZ Publish 4 (the INSTALL file)
+
+2. Edit extension/ezperformancelogger/settings/site.ini.append.php, and disable the preoutput event listener, by
+   commenting away the following line:
+
+       Listeners[]=response/preoutput@eZPerfLogger::preoutput
+
+3. Edit your web/index.php file and add ...
+
+4. If in ezperformancelogger.ini you have set up any loggers which needs to rewrite output, edit services.yml: ...
+
+5. clear all caches (both eZ4 and eZ5 ones)

README

@@ -22,7 +22,7 @@ not in production environments.
 
 Requirements:
 -------------
-. eZP >= 4.6 or 5.X (when running the Legacy Stack only)
+. eZP >= 4.6 or 5.X (NB: when running eZ5 in anything else but Legacy-Stack-only mode, you will need eZPerformanceLoggerBundle as well)
 . apache webserver recommended
 . optionally: either a piwik or ga account
 . optionally: the xhprof profiler and graphviz
@@ -36,9 +36,9 @@ How it works: performance logging
   . 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)
+  . 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)
 
@@ -82,7 +82,7 @@ Notes:
 - 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
+  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
@@ -91,11 +91,13 @@ Notes:
       eZPerfLogger::registerShutdownPerfLogger();
   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;
+  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
 
@@ -118,7 +120,7 @@ How it works: profiling
   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
+  it is enabled any numbers logged for memory or execution time will be useless
 
 - for more info on XHProf, Google is your friend
 

doc/changelogs/changelog-0.12-to-0.13

@@ -0,0 +1,9 @@
+changelog from version 0.12 to 0.13 - released 2014.xx
+
+* New features
+
+- Added installation instructions for eZ Publish 5 stacks - NB: a bundle is also needed for that!!!
+
+* Bugfixes
+
+* Changes

doc/specs_version_5

@@ -0,0 +1,60 @@
+Technical analysis for the port to eZ Publish 5.x
+=================================================
+
+As Is
+-----
+
+The execution hooks which are available in eZ Publish 5.0 and later are different from the ones in eZP version 4.
+
+## eZ4 hooks:
+
+$scriptStartTime (global var) time is taken right at the top of index.php
+
+OutputFilterName => only used up to 4.7
+
+response/preoutput => in ezp 4.5 to 4.7: fired immediately after OutputFilterName
+                      in 5.0 and later: fired inside eZDisplayResult(), mostly from ezpKernelWeb
+
+ezexecution cleanup handler => only since version XXX
+                               Automatically activated when using the tracing db handler AND changing ini settings in
+                               ezperformancelogger.ini.
+                               Fired at ???
+
+## eZ5 hooks:
+
+$scriptStartTime (global var) is not defined. ezpkernelweb::requestInit() measures eZDebug::$ScriptStart. The symfony
+kernel does measure its start time, but only when in development mode.
+
+index.php is free to edit by developers:
+  1. can measure $scriptStartTime in there
+  2. can use a Symfony kernel event handler to measure data, and maybe even manipulate output =>
+     - advantage: it runs only once
+     - it has access to response text, status code, and the legacy kernel
+     - it runs at the very end, possibly after output echoing to screen (good as long as you do not want to log to in-page)
+     - it allows us to disable response/preoutput filter (tested for both frontend and backend/legacy mode)
+     - what about cleanup handler registered via registerShutdownPerfLogger? => it is not enabled by default, luckily.
+       The problem with it is that cleanup handlers do get called on each runcallback() call ( see issue EZP-...), and
+       have no way to know if they are 'the real last one'...
+     - how does it cope with ez4 'eZExecution::cleanExit' ?
+       Apparently fine. Tested when logging content being edited (redirects) and with ggsysinfo json modules
+     - does not run in legacy context => an extra kernel switch is needed for all ini settings to be read. But this happens
+       after output rendering, so there should be no perceived delay from the end user
+  3. for best timing measure and less perf impact, using a post-response Sf event handler is recommended to log data,
+     but if the loggers enabled need to rewrite output, a response-filter event handler is needed instead.
+     Adding 2 handlers works, even though it makes the code a bit more complicated.
+     The downside is that the developer has to explicitly choose which mode to enable - by editing services.yml
+
+
+New features ideas and possibilities
+------------------------------------
+
+* Reporting data back to the sf debug toolbar / profiler: see EzPublishDataCollector as basic example
+
+* Test using aspect-driven libraries to inject timing points to existing services/methods without having to modify the code
+  of the base classes as we are forced to do for eZ4 (see the tracers directory...)
+
+* Could we just reuse code from the Symfony profiler?
+
+* Add simple-to-enable tracers for Doctrine db connection, and for the SPI, Stash, ...
+
+* Add twig tpl operators for timing points (can we just reuse the ones recently introduced in Symfony?)

doc/todo.txt

@@ -1,7 +1,8 @@
 perf logging:
 . improve integration with eZ5 and eZ-LS
-  . make all loggers which rewrite output actually work
-  . all other stuff... quite a lot is left
+  . test all loggers which rewrite output: do they actually work in eZ5 mode?
+  . test again logging on pages which do redirects: does it work or not?
+  . test installation via composer, starting with eZP 5.0
 . self-contained db logging
   . direct-to-db logging
   . import parsed data to db (and aggregate it to a data-cube)