perftools / xhgui-collector
Library for collecting and storing XHProf results for later use by XHGUI.
Installs: 622 546
Dependents: 5
Suggesters: 2
Security: 0
Stars: 33
Watchers: 5
Forks: 34
Open Issues: 1
Requires
- php: >=5.3.0
- paragonie/random_compat: >=2.0
Suggests
- ext-curl: You need to install the curl extension to upload saved files
- ext-mongo: Mongo is needed to store profiler results for PHP < 7.
- ext-mongodb: Mongo is needed to store profiler results for PHP > 7.
- ext-pdo: You need to install the pdo extension to store profiler results to a relational database
- ext-uprofiler: You need to install either xhprof or uprofiler to use XHGui.
- ext-xhprof: You need to install either xhprof or uprofiler to use XHGui.
- alcaeus/mongo-php-adapter: Mongo PHP Adapter is required for PHP >7 (when using ext-mongodb)
README
XHGUI Collector
This is a small standalone module which you can use to collect and store XHProf performance data for later usage in XHGUI.
NOTE: This package is being phased out, in new installatons, use perftools/php-profiler package.
Goals
- Compatibility with PHP >= 5.3.0
- No dependencies aside from the relevant extensions
- Customizable and configurable so you can build your own logic on top of it
XHGUI Compatibility
This project was originally forked from perftools/xhgui@133051f, which was after the tag 0.7.1.
This should ensure compatibility for most tags up to 0.7.1 (included).
The only change that would break compatibility would be a schema change on the XHGUI side.
This table represents current known information about compatibility between this project and XHGUI data schema.
XHGUI Collector version | XHGUI Version | Compatibility |
---|---|---|
1.0.0 - 1.x | 0.2.0 - 0.9.0 | presumed compatible - no schema changes |
Usage
Profile an Application or Site
The simplest way to profile an application is to use external/header.php
.
external/header.php
is designed to be combined with PHP's
auto_prepend_file directive. You can enable auto_prepend_file
system-wide
through php.ini
. Alternatively, you can enable auto_prepend_file
per virtual
host.
With apache this would look like:
<VirtualHost *:80> php_admin_value auto_prepend_file "/Users/markstory/Sites/xhgui/external/header.php" DocumentRoot "/Users/markstory/Sites/awesome-thing/app/webroot/" ServerName site.localhost </VirtualHost>
With Nginx in fastcgi mode you could use:
server { listen 80; server_name site.localhost; root /Users/markstory/Sites/awesome-thing/app/webroot/; fastcgi_param PHP_VALUE "auto_prepend_file=/Users/markstory/Sites/xhgui/external/header.php"; }
Profile a CLI Script
The simplest way to profile a CLI is to use external/header.php
.
external/header.php
is designed to be combined with PHP's
auto_prepend_file directive. You can enable auto_prepend_file
system-wide
through php.ini
. Alternatively, you can enable include the header.php
at the
top of your script:
<?php require '/path/to/xhgui/external/header.php'; // Rest of script.
You can alternatively use the -d
flag when running php:
php -d auto_prepend_file=/path/to/xhgui/external/header.php do_work.php
Use with environment variables
- run
composer require perftools/xhgui-collector
- include these lines into your bootstrap file (e.g. index.php)
define('XHGUI_CONFIG_DIR', PATH_TO_OWN_CONFIG);
require_once PATH_TO_YOUR_VENDOR . '/perftools/xhgui-collector/external/header.php';
- set environment variables to configure the mongodb host, database name and more
env | description | example | default |
---|---|---|---|
XHGUI_MONGO_URI |
the host and port to the mongo db | XHGUI_MONGO_URI=mongo:27017 |
127.0.0.1:27017 |
XHGUI_MONGO_DB |
the database name for the profiling data | XHGUI_MONGO_DB=xhprof |
xhprof |
XHGUI_PROFILING_RATIO |
the ratio of profiled requests | XHGUI_PROFILING_RATIO=50 which profiles 50% of all requests |
XHGUI_PROFILING_RATIO=100 |
XHGUI_PROFILING |
if this env var is set with any value the profiling is enabled | XHGUI_PROFILING=enabled |
it is not set per default, so no profiling will be triggered |
System Requirements
For using the data collection classes you will need the following:
- PHP version 5.3 or later.
- XHProf, Uprofiler or Tideways to actually profile the data.
- Some way to access a MongoDB server. Choose either:
- MongoDB Extension>=1.3.0 (MongoDB PHP driver from pecl)
alcaeus/mongo-php-adapter
composer dependency.
- a MongoDB server. XHGUI requires version 2.2.0 or later.
When in doubt, refer to XHGUI repository's composer.json or this
repository's composer.json suggests
section.