README

一个用于将性能分析提交到 XHGui 的 PHP 性能分析库。

支持的性能分析器

• Tideways XHProf v5.x: PHP >= 7.0
• XHProf: PHP >= 5.3, PHP >= 7.0
• Tideways v4.x: PHP >= 7.0
• UProfiler: PHP >= 5.3, < PHP 7.0

此性能分析库将自动检测任何支持的性能分析器并使用它。可以通过 profiler 配置键选择特定的性能分析器。

目标

• 与 PHP >= 5.3.0 兼容
• 除了相关的扩展之外没有其他依赖
• 可定制和可配置，以便您可以在其之上构建自己的逻辑

使用方法

为了分析您的应用程序，您需要

• 安装此软件包
• 安装性能分析扩展
• 实例化性能分析器
• 配置保存器以将数据发送到 XHGui
• 导入 jsonl 文件（可选）

安装

安装此软件包的推荐方式是通过 composer

composer require perftools/php-profiler

创建性能分析器

创建性能分析器可能如下所示

<?php

// Add this block inside some bootstrapper or other "early central point in execution"
try {
    /**
     * The constructor will throw an exception if the environment
     * isn't fit for profiling (extensions missing, other problems)
     */
    $profiler = new \Xhgui\Profiler\Profiler($config);

    // The profiler itself checks whether it should be enabled
    // for request (executes lambda function from config)
    $profiler->start();
} catch (Exception $e){
    // throw away or log error about profiling instantiation failure
}

如果您需要在分析结束时禁用性能分析器执行 flush、session_write_close 和 fastcgi_finish_request，请将 false 传递给注册关闭处理程序

$profiler->start(false);

使用配置文件

您可以创建 config/config.php 并从中加载配置

1. 将 config/config.default.php 复制到 config/config.php
2. 使用 Config::create() 创建 new Profiler

// Config::create() will load config/config.default.php
// and then merge with config/config.php (if it exists).
$config = \Xhgui\Profiler\Config::create();
$profiler = new \Xhgui\Profiler\Profiler($config);

高级使用

您可能希望自行控制捕获和发送，也许在发送之前修改数据。

/** @var \Xhgui\Profiler\Profiler $profiler */
// start profiling
$profiler->enable($flags, $options);

// run program
foo();

// stop profiler
$profiler_data = $profiler->disable();

// send $profiler_data to saver
$profiler->save($profiler_data);

自动加载器

为了能够分析自动加载器，本项目提供 autoload.php，该文件加载启动性能分析器所需的类。

在加载 composer 自动加载器之前加载它

require_once '/path/to/your/project/vendor/perftools/php-profiler/autoload.php';

$profiler = new \Xhgui\Profiler\Profiler($config);
$profiler->start();

require_once '/path/to/your/project/vendor/autoload.php';

当直接将结果保存到 MongoDB 或 PDO 时，仍然需要加载 composer 自动加载器。

配置

可配置项的参考配置

• examples/autoload.php

它包含所有配置选项及其选项的内置文档。

保存器

要将捕获的数据传递到 XHGui，您需要使用其中一个保存器将其提交到 XHGui 所使用的存储数据。

• 堆栈保存器
• 上传保存器
• 文件保存器
• MongoDB 保存器（已弃用）
• PDO 保存器（已弃用）
• 自定义保存器 自定义保存器

堆栈保存器

允许保存到多个处理程序。

示例配置配置为使用上传保存器，如果失败，则保存到文件保存器

    'save.handler' => \Xhgui\Profiler\Profiler::SAVER_STACK,
    'save.handler.stack' => array(
        'savers' => array(
            \Xhgui\Profiler\Profiler::SAVER_UPLOAD,
            \Xhgui\Profiler\Profiler::SAVER_FILE,
        ),
        // if saveAll=false, break the chain on successful save
        'saveAll' => false,
    ),
    // subhandler specific configs
    'save.handler.file' => array(
        'filename' => '/tmp/xhgui.data.jsonl',
    ),
    'save.handler.upload' => array(
        'url' => 'https://example.com/run/import',
        'timeout' => 3,
        'token' => 'token',
    ),

上传保存器

这是推荐的保存器，因为它最容易设置。

示例配置

    'save.handler' => \Xhgui\Profiler\Profiler::SAVER_UPLOAD,

    // Saving profile data by upload is only recommended with HTTPS
    // endpoints that have IP whitelists applied.
    'save.handler.upload' => array(
        'url' => 'https://example.com/run/import',
        // The timeout option is in seconds and defaults to 3 if unspecified.
        'timeout' => 3,
        // the token must match 'upload.token' config in XHGui
        'token' => 'token',
    ),

文件保存器

如果您的网站无法直接连接到您的 XHGui 实例，您可以选择将数据保存到临时文件，稍后导入到 XHGui。

示例配置

    'save.handler' => \Xhgui\Profiler\Profiler::SAVER_FILE,
    'save.handler.file' => array(
        // Appends jsonlines formatted data to this path
        'filename' => '/tmp/xhgui.data.jsonl',
    ),

有关导入保存文件的说明，请参阅 导入 jsonl 文件 部分。

MongoDB 保存器

注意：不建议直接保存到MongoDB，请使用上传/文件/堆栈保存器。

要直接保存到MongoDB，您需要PHP 5的ext-mongo以及PHP 7的ext-mongodb和alcaeus/mongo-php-adapter包，以及perftools/xhgui-collector包

针对PHP 5

pecl install mongo
composer require perftools/xhgui-collector

针对PHP 7

pecl install mongodb
composer require perftools/xhgui-collector alcaeus/mongo-php-adapter

示例配置

    'save.handler' => \Xhgui\Profiler\Profiler::SAVER_MONGODB,
    'save.handler.mongodb' => array(
        'dsn' => 'mongodb://127.0.0.1:27017',
        'database' => 'xhprof',
        // Allows you to pass additional options like replicaSet to MongoClient.
        // 'username', 'password' and 'db' (where the user is added)
        'options' => array(),
        // Allows you to pass driver options like ca_file to MongoClient
        'driverOptions' => array(),
    ),

PDO 保存器

注意：不建议直接保存到PDO，请使用上传/文件/堆栈保存器。

PDO 保存器应能够保存到任何PDO驱动连接。

您还需要安装perftools/xhgui-collector包

composer require perftools/xhgui-collector

示例配置

    'save.handler' => \Xhgui\Profiler\Profiler::SAVER_PDO,
    'save.handler.pdo' => array(
        'dsn' => 'sqlite:/tmp/xhgui.sqlite3',
        'user' => null,
        'pass' => null,
        'table' => 'results'
    ),

自定义保存器

您可以通过实现SaverInterface并调用setSaver()来创建自己的配置保存器。

use Xhgui\Profiler\Profiler;
use Xhgui\Profiler\Saver\SaverInterface;

class StdOutSaver implements SaverInterface
{
    public function isSupported()
    {
        return true;
    }

    public function save(array $data)
    {
        fwrite(STDOUT, json_encode($data));
    }
}

//...
/** @var Profiler $profiler */
$profiler->setSaver(new StdOutSaver());

导入jsonl文件

您可以使用./bin/import.php脚本来提交由文件保存器保存的文件到XHGui服务器。

1. 设置配置文件
2. 配置为使用上传保存器
3. 执行./bin/import.php脚本

该脚本可以接受多个jsonl格式文件，如果没有给出，则读取标准输入流。

$ ./bin/import.php tests/tmp/php-profiler-xhgui-test-1596093567.787220-c857.json
Imported 1 lines

配置分析速率

您可能希望更改分析应用程序的频率。配置选项profiler.enable允许您提供一个回调函数，以指定要分析哪些请求。

以下示例配置为分析每100个请求中的1个，排除带有/blog URL路径的请求

    'profiler.enable' => function() {
        $url = $_SERVER['REQUEST_URI'];
        if (strpos($url, '/blog') === 0) {
            return false;
        }

        return mt_rand(1, 100) === 42;
    },

相比之下，以下示例指示分析所有请求

    'profiler.enable' => function() {
        return true;
    },

使用XHProf辅助工具进行分析

如果您想使用基于浏览器的工具（如XHProf helper）开始分析，可以使用此方法

    'profiler.enable' => function() {
        return !empty($_COOKIE['_profiler']);
        // or
        return !empty($_COOKIE['XHProf_Profile']);
    },

配置'简单' URL创建

此库为每个收集的配置文件生成'简单' URL。这些URL用于生成在URL视图中使用的汇总数据。由于不同的应用程序对URL映射到代码逻辑块有不同的要求，因此配置选项profile.simple_url允许您提供生成简单URL的逻辑。

默认情况下，查询字符串中的所有数值都将被删除。

    'profile.simple_url' => function($url) {
        return preg_replace('/=\d+/', '', $url);
    },

配置忽略的函数

您可以使用配置值profiler.options为分析器扩展设置附加选项。当您想从分析器数据中排除特定函数时，这很有用。

    'profiler.options' => array(
        'ignored_functions' => array(
            'call_user_func',
            'call_user_func_array',
        ),
    ),
);

此外，如果您不想分析所有PHP内置函数，请将ProfilingFlags::NO_BUILTINS添加到'profiler.flags'。

安装分析器

为了使此库捕获分析数据，您需要安装任何分析器扩展。根据您的环境（PHP版本），您可能需要安装不同的扩展。

支持的性能分析器

• Tideways XHProf v5.x: PHP >= 7.0
• XHProf: PHP >= 5.3, PHP >= 7.0
• Tideways v4.x: PHP >= 7.0
• UProfiler: PHP >= 5.3, < PHP 7.0

Tideways XHProf（5.+）

Tideways XHProf v5.x需要PHP >= 7.0。

要安装tideways_xhprof扩展，请参阅他们的安装文档。

或者，在brew（macOS）上，您可以使用kabel/pecl tap中的包

brew install kabel/pecl/php@7.4-tideways-xhprof
brew install kabel/pecl/php@8.0-tideways-xhprof
brew install kabel/pecl/php@8.1-tideways-xhprof

对于过时的PHP版本，glensc/tap tap中存在一些配方

brew install glensc/tap/php@7.1-tideways-xhprof

XHProf

XHProf支持所有PHP版本。

• xhprof 0.9.x需要PHP >= 5.3，< PHP 7.0
• xhprof 2.x需要PHP >= 7.0

针对PHP 5.x

pecl install xhprof-0.9.4

针对PHP >=7.0

pecl install xhprof

或者，在brew（macOS）上，您可以使用kabel/pecl tap中的包

brew install kabel/pecl/php@7.4-xhprof
brew install kabel/pecl/php@8.0-xhprof
brew install kabel/pecl/php@8.1-xhprof

Tideways（4.x）

Tideways 4.x扩展需要PHP >= 7.0。

要安装 tideways 扩展，请参阅他们的安装文档。

curl -sSfL https://github.com/tideways/php-xhprof-extension/archive/v4.1.6.tar.gz | tar zx
cd php-xhprof-extension-4.1.6/
phpize
./configure
make
make install
echo extension=/usr/local/lib/php/pecl/20160303/tideways.so | tee /usr/local/etc/php/7.1/conf.d/ext-tideways.ini

UProfiler

UProfiler 需要 PHP >= 5.3，< PHP 7.0

要安装 uprofiler 扩展，请参阅他们的安装文档。