phpray

PHPRay

记录每一次 PHP 请求。了解是哪个插件、哪条查询，以及从何时开始。

PHPRay 为 PHP 提供始终开启的请求追踪。它会记录每一次请求的墙钟时间、CPU、内存、SQL、出站 HTTP、错误和 N+1 模式，而不是抽样记录；此外，还会针对一小部分请求，提供按插件／组件划分的耗时明细。无论是一个站点还是一百个客户站点，都使用同一套安装，并集中显示在一个列表中。

它由 PHP 扩展和本地收集器组成。不需要需要 root 权限的 Agent，PHP 进程无需访问外部网络，也不需要 SaaS 账户。它可在共享主机（CageFS、LiteSpeed lsphp、mod_php）、VPS 和容器中运行，支持 PHP 8.0–8.5、glibc 和 musl，以及 amd64 和 arm64。

curl -fsSL https://phpray.dev/install.sh -o phpray-install.sh
less phpray-install.sh          # it asks for root; read it first
sudo bash phpray-install.sh && phpray top

流量运行几分钟后，phpray report --domain example.com --share 就会生成一个可发送给客户的链接：站点名称会被移除，链接会过期，接收者无需安装任何东西即可查看。

想先看看再安装？ 有三种方式，无需 root 权限、账户或银行卡：

• 来自生产环境 WooCommerce 商店的真实报告 — 一个 HTML 文件，已移除站点名称。这是真实输出，不是样板。
• 查看实时流量的控制台 — 只读，无需注册。
• 让 Agent 连接：claude mcp add --transport http phpray https://phpray.dev/mcp 会使用相同的演示数据作答，无需密钥（详情）。

外观一览

PHPRay Cloud：先看所有站点，再看一个站点，然后查看一个耗时 887 ms 的请求，拆分 PHP 和数据库耗时、消耗这些时间的插件，以及背后的查询。演示数据。

它能回答的问题

“商店上周变慢了”并不能指导行动。PHPRay 会明确指出相关插件、查询，以及问题发生变化的日期：

如果你负责管理多个站点

上面大部分内容针对的是单台服务器。更棘手的是另一种情况：四十个并非由你搭建、托管服务也不是你选的站点，而客户今天正在问结账为什么变慢。

• 用一个列表代替四十个面板。 在一个控制台中查看所有站点的请求、p95、错误率和数据库占比，并按当前故障情况排序 — 然后点一下即可查看单个请求。在线演示 展示了一家代理机构的十个站点，只读，无需账户。
• 可在客户实际使用的环境中安装。 共享主机无需 root 权限，一次处理一个账户：扩展从账户自己的 php.ini 加载，或者使用 WordPress 插件，无需扩展或守护进程。切勿在共享服务器上为整个 PHP 版本启用扩展 — 应按账户安装。
• 可发送给客户的报告。 phpray report -domain shop.example -share 会发布分析结果并打印链接。站点名称会被移除，链接会过期且不会被索引。无需账户，也无需银行卡。
• 适用于托管服务提供商。 提供 DirectAdmin 插件，管理员可查看所有账户，用户可查看自己的账户，并附带可自托管的控制台 — 详见 Host Edition。

本地核心部分采用 Apache-2.0 许可，没有任何限制：站点、服务器和请求数量不限，数据保存在你自己的磁盘上。收费的是托管控制台，它会将这些站点集中显示在一个列表中 — 按列表中的站点数量定价，提供一个免费站点起步的方案。价格请见 phpray.dev/en/pricing。

为什么还需要另一个分析器

• 分析每个请求，而非抽样。 抽样分析器会在样本之间累积统计数据。 PHPRay 会为每个请求写入一条记录，因此，当你查看时，那个唯一失败的结账请求和只触发过一次的错误依然会在那里。
• 开销足够低，可以一直启用，而且我们测量过。 在一个渲染耗时 48 ms 的 WordPress 页面上，关闭函数观察器进行跟踪时，五轮交错测试的结果与基线无法区分；而开启观察器（当前默认设置）后，页面耗时为 50 ms。测量方法、原始数据和注意事项： 基准测试。Xdebug 会为每次函数调用添加检测，这就是为什么你只会在有意为之时才开启它。
• 有意对开销较大的部分进行抽样。 默认情况下，函数级分析会覆盖 3 % 的请求。在生产流量中测量每个请求的每次调用，开销会超过流量本身。请注意这个实际情况：让这一切成为可能的观察器会在每个请求中注册，这就是上文提到的 2 ms 开销的来源。如果你想要开销最低的常驻层，并且只在调查问题时开启细分分析，请设置 phpray.profile_functions=0。
• 专为共享主机打造，你也可以自行安装。 无需占用系统资源的守护进程，也无需 Agent 二进制文件。扩展会通过共享内存或普通文件与本地收集器通信。如果你的主机允许你编辑自己的 php.ini——例如 cPanel MultiPHP INI Editor、CloudLinux PHP Selector、Plesk——就可以将 extension= 指向你主目录中的 .so 文件，并以自己的用户身份运行收集器。无需 root 权限、编译器，也无需他人授权。已通过 uid 1000 的端到端验证；无法运行的情况列在文档中。

构建团队

由 IQhost 构建。IQhost 是一家为数千个站点运行 PHP 的欧洲主机服务商。PHPRay 在这里开发，也在这里率先部署：本 README 中提到的共享主机限制并非假设，而是该扩展每天都必须适应的环境。

询问 Agent 哪些地方运行缓慢

PHPRay 内置 MCP 服务，因此编码 Agent 可以读取你的跟踪数据，并回答“哪个插件拖慢了这个页面”，无需你打开仪表板。

无需安装或注册账号即可试用——你会获得一个只读演示账号，其中包含某个真实 WooCommerce 商店记录的流量：

claude mcp add --transport http phpray https://phpray.dev/mcp

然后询问：哪些页面最慢，哪个 SQL 指纹开销最大，哪个插件耗时最多。 添加 --header "Authorization: Bearer <console token>"，即可通过相同的工具读取你自己的站点数据。

或者将其作为二进制文件，通过 stdio 在本地运行：

# pick your platform: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64
curl -fsSL -o phpray-mcp "https://phpray.dev/dl/$(curl -fsS https://phpray.dev/dl/LATEST)/phpray-mcp-linux-amd64"
chmod +x phpray-mcp && sudo mv phpray-mcp /usr/local/bin/

# every server in one place, scoped to your console token
claude mcp add phpray --env PHPRAY_TOKEN=<console token> -- phpray-mcp

# or just this machine's collector, no account needed
claude mcp add phpray-local -- phpray-mcp

在云端模式下，令牌就是你的控制台令牌，因此 Agent 只能看到其获授权访问的站点。在本地模式下，它会读取同一台机器上的收集器，无需任何账号。

10 个只读工具——站点、概览、最慢页面、慢 SQL、组件细分、错误、跟踪记录、完整跟踪记录、前后对比、告警——此外还有第 11 个工具 phpray_profile_url，可针对 URL 前缀开启函数级分析。该工具会改变状态，因此公共演示端点不提供此功能：不提供令牌时，tools/list 会返回 10 个工具。使用你自己的控制台令牌，或通过 stdio 在本地运行时，可使用全部 11 个工具。源码和协议说明：src/mcp/。

免费与付费

此代码库中的所有内容都基于 Apache-2.0 许可免费开源：扩展、收集器、CLI、本地仪表板和控制面板插件。它本身就是一款完整的产品，可在一台服务器上永久使用。

PHPRay Cloud 是付费部分：集中管理多台服务器、保存超出本地磁盘容量的历史数据、提供告警和主机控制面板控制台。它是一个独立的闭源代码库。除非你自行配置服务器密钥，否则此处的任何内容都不会与它通信。

快速开始

curl -fsSL https://phpray.dev/install.sh -o phpray-install.sh
less phpray-install.sh
sudo bash phpray-install.sh
phpray status

直接把安装程序通过管道传给 root shell 并执行，这种习惯并不可取，我们的安装程序也不例外：先下载，再阅读，然后运行。它获取的所有文件的校验和都发布在文件旁边，地址为 https://phpray.dev/dl/<version>/SHA256SUMS，安装程序也会验证这些校验和。

安装程序会检测主机上的每个 PHP 版本，为每个版本安装预构建的 phpray.so，部署带有 systemd 单元的采集器，并重新加载 PHP 池。它是一个不依赖任何外部组件的单一二进制文件。

手动安装

如果你更愿意自行放置各个组件：

# 1. drop the prebuilt extension into your PHP extension dir
sudo cp phpray.so /usr/local/lib/php/extensions/no-debug-non-zts-20240924/

# 2. enable it (Debian layout shown; use your distro's conf.d)
echo "extension=phpray.so" | sudo tee /etc/php/8.3/fpm/conf.d/99-phpray.ini
sudo systemctl reload php8.3-fpm

# 3. run the collector
sudo /usr/local/bin/phpray-collector serve -addr :9191

验证

php -m | grep phpray                       # "phpray" is listed
curl -sI https://yoursite.com              # X-PHPRay-ID: pr-... response header

CLI

phpray status        # extension loaded, collector running, recent volume
phpray top           # live slowest requests, htop-style
phpray trace         # per-request waterfall (queries, HTTP calls, components)
phpray diag shop.pl  # health score + findings + recommendations

可发送给他人的报告

PHPRay 的产物中，经常被从未安装过它的人阅读的只有这一种：代理机构将它发给店主，管理员将它粘贴到工单中。

phpray report -domain shop.example -w 1440 -format html -o report.html
phpray report -domain shop.example -format html -anonymize -o public.html

一个自包含文件——没有外部请求、没有字体、没有脚本——包含运行状况评分、发现的问题、所需成本以及处理建议。使用 -anonymize 后，域名会在所有位置被替换，包括发现的问题和证据中，因此同一份报告可以发布到论坛或放入提案。

人们分享链接，而不是附件，因此也可以将同样的发现发布为网页：

phpray report -domain shop.example -w 60 -share
https://app.phpray.dev/r/dklns4bdbf74bdtetbxhbxtcey

无需账户，也无需银行卡——这可以直接使用此仓库中的采集器。离开服务器的是发现问题的数据，而非文档：网页由我们的模板根据这些数据渲染。所有文本字段中的站点名称都会被移除，证据行也不例外，因此 shop.example/checkout/ 会以 /checkout/ 的形式发布。链接包含 128 位随机数，30 天后过期，且不会被编入索引。-share-url 可让同一条命令指向你自己的控制台副本。

跟踪记录包含什么

每个请求都会生成一条 JSON 记录。经过函数性能分析的请求会带有 "profiled": 1，以及一个 components 数组，其中包含每个组件的 incl_ns、self_ns 和 calls：

{
  "ts": 1774713671,
  "host": "shop.example.com",
  "method": "GET",
  "uri": "/checkout",
  "status": 500,
  "duration_ms": 2411.7,
  "cpu_user_ms": 188.4,
  "memory_peak_mb": 96.2,
  "app": "wp",
  "level": "full",
  "db_count": 142,
  "queries": [
    { "sql": "SELECT * FROM wp_posts WHERE ID = ?", "ms": 12.4 }
  ],
  "http_calls": [
    { "url": "https://api.stripe.com/v1/checkout/sessions", "ms": 1842.9, "status": 200 }
  ],
  "errors": [
    { "type": "E_WARNING", "msg": "Division by zero", "file": "/wp-content/plugins/xyz/fee.php", "t": 1903.1 }
  ],
  "n1": 1,
  "profiled": 1,
  "components": [
    { "name": "plugins/woocommerce", "incl_ns": 1430221, "self_ns": 902114, "calls": 1874 },
    { "name": "themes/storefront",   "incl_ns": 612009,  "self_ns": 504002, "calls": 913 },
    { "name": "core",                "incl_ns": 421778,  "self_ns": 388001, "calls": 1204 }
  ]
}

incl_ns 是在组件内耗费的时间（包括它调用的任何核心代码或其他 PHP 代码）；self_ns 不包括嵌套组件；calls 是该组件中观测到的函数调用次数。

配置

最可能需要调整的六条指令。PERDIR 表示可以按站点或目录覆盖；SYSTEM 表示必须在 php.ini 中设置。

phpray.enabled            = 1        ; PERDIR — master switch
phpray.profile_mode       = sample   ; PERDIR — off | sample | url | all
phpray.profile_sample_rate= 3        ; PERDIR — % of requests function-profiled in "sample"
phpray.profile_url        = /cart    ; PERDIR — URI prefixes to profile in "url" mode
phpray.profile_functions  = 1        ; SYSTEM — register the observer at all (0 = zero cost)
phpray.output_mode        = shm      ; SYSTEM — file | shm | both

其余指令（智能采样阈值、忽略的 URI、环形缓冲区大小、标头发送等）见 docs/ 中的文档。

在 Apache（mod_php / LiteSpeed）下按站点控制，或在对应的池中使用 .user.ini：

# .htaccess — mod_php only
php_value phpray.profile_mode url
php_value phpray.profile_url /checkout

; .user.ini — PHP-FPM / LiteSpeed
phpray.profile_mode = sample
phpray.profile_sample_rate = 5

无论 phpray.enabled 的值如何，所有钩子（MySQL/curl/文件、错误回调和观察器）都会在 MINIT 时安装，因此即使服务器全局禁用，单个站点仍可启用；如果要完全不运行观察器，唯一的方法是设置 phpray.profile_functions = 0。JSONL 记录通过 O_APPEND 描述符执行一次 write() 写入，因此并发工作进程永远不会交错写入行。

开销

常驻跟踪层旨在尽可能减少热路径上的开销。数据是在真实的 WooCommerce 测试商店（Storefront 主题、22 个启用的插件、PHP 8.3 和 OPcache）上通过安装和未安装扩展进行测量的，从未使用合成脚本；完整的方法说明——工作负载、环境、每个数字的测量方式及误差范围——见 docs/。

状态（2026 年 9 月）： 笔记本电脑上的内部运行结果显示，常驻层的开销处于裸 PHP 基线的测量噪声范围内；对每个请求进行性能分析的开销则明显高于基线，但远低于传统 execute_ex 钩子的成本。我们不会将这些数据作为产品数据发布。经过认证的数据、方法说明和原始数据将在专用的安静主机上完成基准测试后公布。

架构

 PHP process
   └─ phpray.so (hooks RINIT/RSHUTDOWN, mysqli/PDO, curl, files, errors, observer)
         │
         └─► ring buffer (/dev/shm)  and/or  JSONL file
                   │
                   ▼
        phpray-collector (single Go binary, systemd unit)
         ├─► SQLite (traces, queries, components, 1-min aggregates, retention)
         ├─► REST API  /api/v1/*  +  embedded dashboard
         └─► (optional) PHPRay Cloud ingest

插件

两者都位于各自的代码仓库中，因为它们有自己的发布周期，而且 WordPress 插件有自己的许可证。

WordPress（GPLv2+）。如果你无法加载 PHP 扩展——例如使用托管式共享主机或 PaaS——该插件就是一个纯 PHP 收集器：它会钩入 $wpdb、HTTP API 和错误处理程序，并将相同格式的跟踪数据发送到本地收集器或 PHPRay Cloud。无需扩展，你也能获得始终运行的监控层（计时、SQL、HTTP、错误、N+1）；README 也明确说明了它无法监测的四项内容。

DirectAdmin（Apache-2.0）。这是一个面板插件，包含两个视图：客户可以查看自己的域名，管理员可以查看整个服务。在 CloudLinux 上，它可以按账户启用或关闭扩展，而 .user.ini 无法做到这一点——PHP 在模块启动很久之后才会读取目录级设置。客户还可以在无需 SSH 的情况下，设置“对此 URL 前缀进行 N 分钟的性能分析”。

PHPRay Cloud

Host Edition 客户以及任何想使用托管控制台的人，都可以将跟踪数据发送到 PHPRay Cloud：多域名集群视图、保留与历史记录、警报，以及面向客户的白标诊断报告。套餐：Free、Solo 每月 19 美元、Studio 每月 99 美元、Agency 每月 249 美元、Fleet 每月 499 美元；Host Edition 按年计费。请参阅 https://phpray.dev/pricing。PHP 扩展和本地收集器仍然免费且开源——云端是可选的目标位置，而非依赖项。

从源代码构建

# extension
cd src/extension
phpize && ./configure --enable-phpray && make -j$(nproc) && sudo make install

# collector
cd src/collector
go build -o phpray-collector .

贡献

我们采用 Developer Certificate of Origin（DCO）。请使用 git commit -s 为每次提交签署认证。进行重大更改前，请先创建议题。

安全

如需报告安全问题，请发送邮件至 [email protected]（网站上提供 PGP 信息）。请勿公开创建议题。

许可证

Apache License, Version 2.0——请参阅 LICENSE。

商标

“PHPRay”是 IQhost 的商标。扩展、收集器和此代码仓库均按上述条款授权；本授权不包含该商标。

---

由 IQhost 构建——这家欧洲托管服务提供商为数千个网站运行 PHP，PHPRay 正是在这里开发并首次部署的。