Skip to content

Commit

Permalink
Merge pull request #293 from glensc/docs-update
Browse files Browse the repository at this point in the history
  • Loading branch information
@glensc
glensc committed Jul 14, 2020
2 parents 97d7c9b + 97dec72 commit bead5b3
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 182 deletions.
254 changes: 79 additions & 175 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -102,32 +118,32 @@ 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:

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
<Directory /var/www/xhgui/>
Options Indexes FollowSymLinks
AllowOverride FileInfo
Require all granted
</Directory>
```
Example configuration for Apache 2.4:

```apache
<Directory /var/www/xhgui/>
Options Indexes FollowSymLinks
AllowOverride FileInfo
Require all granted
</Directory>
```

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.

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/templates/error/view.twig
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{% extends 'layout/base.twig' %}

{% block content %}
<h1>Aw shoot, Xhgui hit an error</h1>
<h1>Aw shoot, XHGui hit an error</h1>

<p>{{ message }}</p>

Expand Down
2 changes: 1 addition & 1 deletion src/templates/layout/base.twig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Xhgui {% block title '' %}</title>
<title>XHGui {% block title '' %}</title>
<link href="{{ static('css/bootstrap.min.css') }}" rel="stylesheet" media="screen">
<link href="{{ static('css/datepicker.css') }}" rel="stylesheet" media="screen">
<link href="{{ static('css/xhgui.css') }}" rel="stylesheet" media="screen">
Expand Down
6 changes: 1 addition & 5 deletions src/templates/runs/list.twig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,7 @@
<div class="hero-unit">
<h3>Looks like you haven't done any profiling</h3>
<p>To get started with XHGUI you'll need to collect some profiling data.</p>
<p>The simplest way to get an application profiled, is to use <code>external/header.php</code>.
This file is designed to be combined with PHP's
<a href="http://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file">auto_prepend_file</a>
directive. This can be enabled system-wide through <code>php.ini</code>. Alternatively, you can enable
<code>auto_prepend_file</code> per virtual host. See the README.md file for more details.
<p>See <a href="https://github.com/perftools/xhgui#profiling-a-web-request-or-cli-script">Profiling a Web Request or CLI script</a> section of the readme file
</p>
</div>
{% endif %}
Expand Down

0 comments on commit bead5b3

Please sign in to comment.