diff --git a/README.md b/README.md index 217ab4089..5bb8b5891 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,54 @@ -xhgui -===== +# xhgui -A graphical interface for XHProf data built on MongoDB. +A graphical interface for XHProf profiling data that can store the results in MongoDB or PDO database. -This tool requires that [XHProf](http://pecl.php.net/package/xhprof) or its one -of its forks [Uprofiler](https://github.com/FriendsOfPHP/uprofiler), -[Tideways](https://github.com/tideways/php-profiler-extension) are installed. -XHProf is a PHP Extension that records and provides profiling data. -XHGui (this tool) takes that information, saves it in MongoDB, and provides -a convenient GUI for working with it. +Application is [profiled](#profiling-a-web-request-or-cli-script) and the +profiling data is transferred to XHGui, which takes that information, saves it +in MongoDB (or PDO database), and provides a convenient GUI for working with +it. [![Build Status](https://travis-ci.org/perftools/xhgui.svg?branch=master)](https://travis-ci.org/perftools/xhgui) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/perftools/xhgui/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/perftools/xhgui/?branch=master) [![Code Coverage](https://scrutinizer-ci.com/g/perftools/xhgui/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/perftools/xhgui/?branch=master) -System Requirements -=================== +# System Requirements XHGui has the following requirements: - * PHP version 5.6 up to 7.3. - * [MongoDB Extension](http://pecl.php.net/package/mongodb) MongoDB PHP driver. - XHGui requires verison 1.3.0 or later. - * [MongoDB](http://www.mongodb.org/) MongoDB Itself. XHGui requires version 2.2.0 or later. - * One of [XHProf](http://pecl.php.net/package/xhprof), - [Uprofiler](https://github.com/FriendsOfPHP/uprofiler) or - [Tideways](https://github.com/tideways/php-profiler-extension) to actually profile the data. - * [dom](http://php.net/manual/en/book.dom.php) If you are running the tests - you'll need the DOM extension (which is a dependency of PHPUnit). +- PHP version 5.6 up to 7.3. +- If using MongoDB storage, see [MongoDB](#MongoDB) requirements +- If using PDO storage, see [PDO](#PDO) requirements +- To profile an application, one of the profiling PHP extensions is required. + See [Profiling a Web Request or CLI script](#profiling-a-web-request-or-cli-script). + The extension is not needed to run XHGui itself. +## MongoDB -Installation from source -======================== +The default installation uses MongoDB database. Most of the documentation speaks about MongoDB. + +- [MongoDB Extension][ext-mongodb] MongoDB PHP driver. + XHGui requires verison 1.3.0 or later. +- [MongoDB][mongodb] MongoDB Itself. XHGui requires version 2.2.0 or later. + +[ext-mongodb]: https://pecl.php.net/package/mongodb +[mongodb]: https://www.mongodb.com/ + +## PDO + +- [PDO][ext-pdo] PHP extension + +Any of the drivers and accompanying database: + +- [SQLite (PDO)][ext-pdo_sqlite] +- [MySQL (PDO)][ext-pdo_mysql] +- [PostgreSQL (PDO)][ext-pdo_pgsql] + +[ext-pdo]: https://www.php.net/manual/en/book.pdo.php +[ext-pdo_sqlite]: https://www.php.net/manual/en/ref.pdo-sqlite.php +[ext-pdo_mysql]: https://www.php.net/manual/en/ref.pdo-mysql.php +[ext-pdo_pgsql]: https://www.php.net/manual/en/ref.pdo-pgsql.php + +# Installation from source 1. Clone or download `xhgui` from GitHub. @@ -85,8 +102,7 @@ Installation from source 8. Set up your webserver. The Configuration section below describes how to setup the rewrite rules for both nginx and apache. -Installation with Docker -======================== +# Installation with Docker This setup uses [docker-compose] to orchestrate docker containers. @@ -102,11 +118,9 @@ This setup uses [docker-compose] to orchestrate docker containers. [docker-compose]: https://docs.docker.com/compose/ -Configuration -============= +# Configuration -Configure Webserver Re-Write Rules ----------------------------------- +## Configure Webserver Re-Write Rules XHGui prefers to have URL rewriting enabled, but will work without it. For Apache, you can do the following to enable URL rewriting: @@ -114,20 +128,22 @@ For Apache, you can do the following to enable URL rewriting: 1. Make sure that an .htaccess override is allowed and that AllowOverride has the directive FileInfo set for the correct DocumentRoot. - Example configuration for Apache 2.4: - ```apache - - Options Indexes FollowSymLinks - AllowOverride FileInfo - Require all granted - - ``` + Example configuration for Apache 2.4: + + ```apache + + Options Indexes FollowSymLinks + AllowOverride FileInfo + Require all granted + + ``` + 2. Make sure you are loading up mod_rewrite correctly. You should see something like: - ```apache - LoadModule rewrite_module libexec/apache2/mod_rewrite.so - ``` + ```apache + LoadModule rewrite_module libexec/apache2/mod_rewrite.so + ``` 3. XHGui comes with a `.htaccess` file to enable the remaining rewrite rules. @@ -156,128 +172,32 @@ server { } ``` +# Profiling a Web Request or CLI script -Configure XHGui Profiling Rate -------------------------------- - -After installing XHGui, you may want to change how frequently you -profile the host application. The `profiler.enable` configuration option -allows you to provide a callback function that specifies the requests that -are profiled. By default, XHGui profiles 1 in 100 requests. +The recommended way tho profile an application is to use [perftools/php-profiler] package. -The following example configures XHGui to only profile requests -from a specific URL path: +You can use that package to collect data from your web applications and CLI +scripts. -The following example configures XHGui to profile 1 in 100 requests, -excluding requests with the `/blog` URL path: +This data is then pushed into XHGui database where it can be viewed with this +application. -```php -// In config/config.php -return array( - // Other config - 'profiler.enable' => function() { - $url = $_SERVER['REQUEST_URI']; - if (strpos($url, '/blog') === 0) { - return false; - } - return rand(1, 100) === 42; - } -); -``` +It offers submitting data directly to XHGui instance once the profiling is +complete at the end of the request. -In contrast, the following example configured XHGui to profile *every* -request: - -```php -// In config/config.php -return array( - // Other config - 'profiler.enable' => function() { - return true; - } -); -``` - - -Configure 'Simple' URLs Creation --------------------------------- - -XHGui generates 'simple' URLs for each profile collected. These URLs are -used to generate the aggregate data used on the URL view. Since -different applications have different requirements for how URLs map to -logical blocks of code, the `profile.simple_url` configuration option -allows you to provide specify the logic used to generate the simple URL. -By default, all numeric values in the query string are removed. - -```php -// In config/config.php -return array( - // Other config - 'profile.simple_url' => function($url) { - // Your code goes here. - } -); -``` - -The URL argument is the `REQUEST_URI` or `argv` value. - -Configure ignored functions ---------------------------- - -You can use the `profiler.options` configuration value to set additional options -for the profiler extension. This is useful when you want to exclude specific -functions from your profiler data: - -```php -// In config/config.php -return array( - //Other config - 'profiler.options' => [ - 'ignored_functions' => ['call_user_func', 'call_user_func_array'] - ] -); -``` - -In addition, if you do not want to profile all PHP built-in functions, -you can make use of the `profiler.skip_built_in` option. - -Profiling a Web Request or CLI script -===================================== - -Using [xhgui-collector](https://github.com/perftools/xhgui-collector) you can -collect data from your web applications and CLI scripts. This data is then -pushed into xhgui's database where it can be viewed with this application. - -Saving & Importing Profiles ---------------------------- - -If your site cannot directly connect to your MongoDB instance, you can choose -to save your data to a temporary file for a later import to XHGui's MongoDB -database. - -To configure XHGui to save your data to a temporary file, -change the `save.handler` setting to `file` and define your file's -path with `save.handler.filename`. - -To import a saved file to MongoDB use XHGui's provided -`external/import.php` script. - -Be aware of file locking: depending on your workload, you may need to -change the `save.handler.filename` file path to avoid file locking -during the import. - -The following demonstrate the use of `external/import.php`: +If the site cannot directly connect to XGHui instance, the package offers +solution to capture profiling data to file which you can import using +`external/import.php` script: ```bash -php external/import.php -f /path/to/file +php external/import.php -f /path/to/jsonlinesfile.jsonl ``` -**Warning**: Importing the same file twice will load twice the run datas inside -MongoDB, resulting in duplicate profiles +**Warning**: Importing the same file twice will create duplicate profiles. +[perftools/php-profiler]: https://github.com/perftools/php-profiler -Limiting MongoDB Disk Usage ---------------------------- +## Limiting MongoDB Disk Usage Disk usage can grow quickly, especially when profiling applications with large code bases or that use larger frameworks. @@ -298,8 +218,7 @@ $ mongo > db.results.ensureIndex( { "meta.request_ts" : 1 }, { expireAfterSeconds : 432000 } ) ``` -Waterfall Display ------------------ +## Waterfall Display The goal of XHGui's waterfall display is to recognize that concurrent requests can affect each other. Concurrent database requests, CPU-intensive @@ -310,33 +229,18 @@ profiling a sample of requests, the waterfall fills you with impolite lies. Some Notes: - * There should probably be more indexes on MongoDB for this to be performant. - * The waterfall display introduces storage of a new `request_ts_micro` value, as second level - granularity doesn't work well with waterfalls. - * The waterfall display is still very much in alpha. - * Feedback and pull requests are welcome :) - -Using Tideways Extension -======================== - -The XHProf PHP extension is not compatible with PHP7.0+. Instead you'll need to -use the [tideways_xhprof extension](https://github.com/tideways/php-profiler-extension). - -Once installed, you can use the following configuration data: - -```ini -[tideways_xhprof] -extension="/path/to/tideways/tideways_xhprof.so" -``` +- There should probably be more indexes on MongoDB for this to be performant. +- The waterfall display introduces storage of a new `request_ts_micro` value, as second level + granularity doesn't work well with waterfalls. +- The waterfall display is still very much in alpha. +- Feedback and pull requests are welcome :) -Releases / Changelog -==================== +# Releases / Changelog -See the [releases](https://github.com/preinheimer/xhgui/releases) for changelogs, +See the [releases](https://github.com/perftools/xhgui/releases) for changelogs, and release information. -License -======= +# License Copyright (c) 2013 Mark Story & Paul Reinheimer diff --git a/src/templates/error/view.twig b/src/templates/error/view.twig index b799dd768..975acf312 100644 --- a/src/templates/error/view.twig +++ b/src/templates/error/view.twig @@ -1,7 +1,7 @@ {% extends 'layout/base.twig' %} {% block content %} -

Aw shoot, Xhgui hit an error

+

Aw shoot, XHGui hit an error

{{ message }}

diff --git a/src/templates/layout/base.twig b/src/templates/layout/base.twig index 87f53fc46..eb0f49d17 100644 --- a/src/templates/layout/base.twig +++ b/src/templates/layout/base.twig @@ -2,7 +2,7 @@ - Xhgui {% block title '' %} + XHGui {% block title '' %} diff --git a/src/templates/runs/list.twig b/src/templates/runs/list.twig index 47c4f74db..0a7b9160f 100644 --- a/src/templates/runs/list.twig +++ b/src/templates/runs/list.twig @@ -45,11 +45,7 @@

Looks like you haven't done any profiling

To get started with XHGUI you'll need to collect some profiling data.

-

The simplest way to get an application profiled, is to use external/header.php. - This file is designed to be combined with PHP's - auto_prepend_file - directive. This can be enabled system-wide through php.ini. Alternatively, you can enable - auto_prepend_file per virtual host. See the README.md file for more details. +

See Profiling a Web Request or CLI script section of the readme file

{% endif %}