isabella232 / xhgui-collector

Data collector package for xhgui. Enables host applications to push data into an xhgui instance

XHGUI Collector

This is a small standalone module which you can use to collect and store XHProf performance data for later usage in XHGUI.

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.