forp PHP profiler

Introduction

forp is a lightweight PHP extension which provides PHP profile datas.

Summary of features :

measurement of time and allocated memory for each function

CPU usage

file and line number of the function call

output as Google’s Trace Event format

caption of functions

grouping of functions

aliases of functions (useful for anonymous functions)

forp is non intrusive, it provides PHP annotations to do its work.

Hello world

Example :

<?php // first thing to do, enable forp profiler forp_start (); // here, our PHP code we want to profile function foo () { echo "Hello world !

" ; }; foo (); // stop forp buffering forp_end (); // get the stack as an array $profileStack = forp_dump (); print_r ( $profileStack );

Result :

Hello world ! Array ( [utime] => 0 [stime] => 0 [stack] => Array ( [0] => Array ( [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php [function] => {main} [usec] => 94 [pusec] => 6 [bytes] => 524 [level] => 0 ) [1] => Array ( [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php [function] => foo [lineno] => 10 [usec] => 9 [pusec] => 6 [bytes] => 120 [level] => 1 [parent] => 0 ) ) )

Example with annotations

Example :

<?php // first thing to do, enable forp profiler forp_start (); /** * here, our PHP code we want to profile * with annotations * * @ProfileGroup("Test") * @ProfileCaption("Foo #1") * @ProfileAlias("foo") */ function fooWithAnnotations ( $bar ) { return 'Foo ' . $bar ; } echo "foo = " . fooWithAnnotations ( "bar" ) . "

" ; // stop forp buffering forp_end (); // get the stack as an array $profileStack = forp_dump (); echo "forp stack =

" ; print_r ( $profileStack );

Result :

foo = Foo bar forp stack = Array ( [utime] => 0 [stime] => 0 [stack] => Array ( [0] => Array ( [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php [function] => {main} [usec] => 113 [pusec] => 6 [bytes] => 568 [level] => 0 ) [1] => Array ( [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php [function] => foo [lineno] => 41 [groups] => Array ( [0] => Test ) [caption] => Foo bar [usec] => 39 [pusec] => 24 [bytes] => 124 [level] => 1 [parent] => 0 ) ) )

php.ini options

forp.max_nesting_level : default 50

forp.no_internals : default 0

forp PHP API

forp_start(flags*) : start forp collector

forp_end() : stop forp collector

forp_dump() : return stack as flat array

forp_print() : display forp stack (SAPI CLI)

forp_start() flags

FORP_FLAG_CPU : activate collect of time

FORP_FLAG_MEMORY : activate collect of memory usage

FORP_FLAG_CPU : retrieve the cpu usage

FORP_FLAG_CAPTION : enable caption handler

FORP_FLAG_ALIAS : enable alias handler

FORP_FLAG_GROUPS : enable groups handler

FORP_FLAG_HIGHLIGHT : enable HTML highlighting

forp_dump()

forp_dump() provides an array composed of :

global fields : utime, stime …

stack : a flat PHP array of stack entries.

Global fields :

utime : CPU used for user function calls

stime : CPU used for system calls

Fields of a stack entry :

file : file of the call

lineno : line number of the call

class : Class name

function : function name

groups : list of associated groups

caption : caption of the function

usec : function time (without the profiling overhead)

pusec : inner profiling time (without executing the function)

bytes : memory usage of the function

level : depth level from the forp_start call

parent : parent index (numeric)

forp_json()

Prints stack as JSON string directly on stdout. This is the fastest method in order to send the stack to a JSON compatible client.

See forp_dump() for its structure.

forp_json_google_tracer()

forp_json_google_tracer($filepath) will output stack as Google Trace Event format.

Usage :

// Start profiler forp_start(); my_complex_function(); // Stop profiler forp_end(); // Get JSON and save it into file forp_json_google_tracer("/tmp/output.json");

Then, open Google Chrome or Chromium browser and go to chrome://tracing/. Load the output file and enjoy the result.

forp_inspect()

forp_inspect(‘symbol’, $symbol) will output a detailed representation of a variable in the forp_dump() result.

Usage :

$var = array(0 => "my", "strkey" => "inspected", 3 => "array"); forp_inspect('var', $var); print_r(forp_dump());

Result :

Array ( [utime] => 0 [stime] => 0 [inspect] => Array ( [var] => Array ( [type] => array [size] => 3 [value] => Array ( [0] => Array ( [type] => string [value] => my ) [strkey] => Array ( [type] => string [value] => inspected ) [3] => Array ( [type] => string [value] => array ) ) ) ) )

Available annotations

Sets groups that function belongs.

/** * @ProfileGroup("data loading","rendering") */ function exec($query) { /* ... */ }

Adds caption to functions. Caption string may contain references (# ) to parameters of the function.

/** * @ProfileCaption("Find row for pk #1") */ public function findByPk($pk) { /* ... */ }

Gives an alias name to a function. Useful for anonymous functions

/** * @ProfileAlias("MyAnonymousFunction") */ $fn = function() { /* ... */ }

Adds a frame around output generated by the function.

/** * @ProfileHighlight("1") */ function render($datas) { /* ... */ }

Demos / UI

forp provides a structure so simple that it’s easy to make your own UI.

But, if you are looking for a user interface with a lot of features, we’ve made a rich JavaScript client : forp-ui

You can see forp in action with the fastest PHP Frameworks :

Build status

Installation, requirements

Requirements

php5-dev

apt-get install php5-dev

Install with Composer

Require forp-PHP-profiler in your project composer.json

"require-dev" : { "aterrien/forp-profiler" : "~1.1" } , "repositories" : [ { "type" : "git" , "url" : "git@github.com:aterrien/forp-PHP-profiler.git" } ]

run Composer install

php composer.phar install

compile

cd vendor/aterrien/forp-profiler/ext/forp phpize ./configure make && make install

and enable forp in your php.ini

extension = forp.so

or opt for “old school” installation

Use current release

wget https://github.com/aterrien/forp/archive/1.1.0.tar.gz tar -xvzf 1.1.0.tar.gz cd 1.1.0/ext/forp

OR dev-master (unstable, at your own risk)

git clone https://github.com/aterrien/forp-PHP-profiler cd forp-PHP-profiler/ext/forp

compile

phpize ./configure make && make install

and enable forp in your php.ini

extension = forp.so

Tested OS and platforms

Apache

Apache/2.2.16 (Debian)

PHP 5.3.8 (cli) (built: Sep 25 2012 22:55:18)

Nginx / php-fpm

nginx version: nginx/1.2.6

PHP 5.3.21-1~dotdeb.0 (fpm-fcgi) PHP 5.4.10-1~dotdeb.0 (fpm-fcgi)

Cloud / AWS

Centos 6.3 (AMI)

Apache/2.2.15 (Unix)

PHP 5.4.13 (cli) (built: Mar 15 2013 11:27:51)

Contributors

Anthony Terrien, Ioan Chiriac, Alexis Okuwa, TOMHTML