XHProf 輕量級效能分析：安裝、整合與生產環境實戰

為什麼選 XHProf？

• Facebook 開源，專為生產環境設計，開銷極低 (約 1-5%)
• 支援 CPU、Memory、Wall Time 多維度分析
• 可程式化控制開關，適合抽樣分析
• 內建 Web UI 視覺化火焰圖與呼叫鏈

安裝步驟 (Linux + PHP 7/8)

# 1. 透過 PECL 安裝 (需 php-dev、autoconf、gcc)
sudo pecl install xhprof

# 2. 啟用擴展 (路徑依 php.ini 而定)
echo "extension=xhprof.so" | sudo tee /etc/php/8.1/mods-available/xhprof.ini
sudo phpenmod xhprof

# 3. 設定輸出目錄 (需可寫入)
sudo mkdir -p /var/tmp/xhprof
sudo chown www-data:www-data /var/tmp/xhprof
echo "xhprof.output_dir=/var/tmp/xhprof" | sudo tee -a /etc/php/8.1/mods-available/xhprof.ini

# 4. 重啟 PHP-FPM
sudo systemctl reload php8.1-fpm

# 5. 驗證
php -m | grep xhprof

部署 Web UI

# 取得原始碼中的 xhprof_html、xhprof_lib 目錄
git clone https://github.com/longxinH/xhprof.git /opt/xhprof
# 或從 PECL 套件解壓
# 設定 Nginx 虛擬主機指向 /opt/xhprof/xhprof_html

基礎使用範例

<?php
// 1. 啟動分析 (可選旗標)
xhprof_enable(XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

// 2. 執行目標代碼
require 'bootstrap.php';
$app->run();

// 3. 停止並取得資料
$data = xhprof_disable();

// 4. 儲存並產生連結
include_once '/opt/xhprof/xhprof_lib/utils/xhprof_lib.php';
include_once '/opt/xhprof/xhprof_lib/utils/xhprof_runs.php';

$runs = new XHProfRuns_Default('/var/tmp/xhprof');
$runId = $runs->save_run($data, 'my_app');

echo '檢視報告';
?>

生產環境無侵入式注入 (推薦)

方案 A：php.ini auto_prepend_file

# /etc/php/8.1/fpm/php.ini
auto_prepend_file = /opt/xhprof/inject.php

<?php
// /opt/xhprof/inject.php
// 僅抽樣 1% 請求
if (mt_rand(1, 100) !== 1) return;

xhprof_enable(XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

register_shutdown_function(function () {
    $data = xhprof_disable();
    if (function_exists('fastcgi_finish_request')) {
        fastcgi_finish_request(); // 先回應用戶，再背景存檔
    }
    $runs = new XHProfRuns_Default('/var/tmp/xhprof');
    $runs->save_run($data, 'prod_sample');
});
?>

方案 B：Nginx 層級注入 (站點級控制)

location ~ \.php$ {
    fastcgi_param PHP_VALUE "auto_prepend_file=/opt/xhprof/inject.php";
    # 其他 fastcgi 參數...
}

報告關鍵指標解讀

火焰圖生成 (需 Graphviz)

sudo apt-get install -y graphviz
# UI 中點擊 [View Full Callgraph] 即可生成 SVG

常見問題排查

• UI 顯示空白：確認 xhprof.output_dir 權限、open_basedir 限制
• Callgraph 報錯：安裝 graphviz 並確保 dot 在 PATH
• 資料量過大：啟用 XHPROF_FLAGS_NO_BUILTINS 忽略內建函數、調高抽樣率門檻
• 多專案隔離：save_run($data, 'project_name') 第二參數區分來源

結語

XHProf 以極低開銷提供生產級效能可見性。關鍵在於：抽樣而非全量、背景存檔不阻塞回應、定期輪轉輸出目錄。配合 CI/CD 管線自動比對基準線，即可構建持續效能守護體系。