Runtime Doctor

To help identify performance bottlenecks, configuration issues, active resource leaks, and event loop problems, Nexphant includes a diagnostics tool called the Runtime Doctor. It is available both as a CLI command and a programmatic API class.

CLI Diagnostics Tool

You can run the Doctor via the Nexphant CLI to audit PHP SAPI extension availability, capabilities, event loop drivers, and configuration recommendations.

php app.php runtime:doctor

Checks Performed by the CLI Command:

1. Core Extensions: Verifies status ([ok] or [missing]) of pcntl, posix, opcache, json, and zlib.
2. Network Extensions: Verifies status of sockets, event, ev, and uv.
3. IPC Extensions: Verifies status of sysvsem, sysvshm, sysvmsg, and shmop.
4. Cache Extensions: Verifies status of apcu and redis.
5. Drivers: Identifies selected active drivers for Event Loop (e.g. FiberEventLoop) and Socket.
6. Capabilities: Lists detected SAPI capabilities (e.g. fibers, cli, sockets).
7. Recommendations: Generates installation commands for missing PHP extensions (such as pecl install event, apt install php-sockets, pecl install apcu).

Programmatic API Diagnostics

For live production monitoring and health check endpoints, run the Doctor programmatically via Doctor:

use Nexphant\Observability\Doctor;

$report = Doctor::run();

if (!$report['healthy']) {
    // Alert or log diagnostics issues
    foreach ($report['issues'] as $issue) {
        error_log("Runtime issue: {$issue['type']} (Severity: {$issue['severity']})");
    }
}

Live Diagnostics Performed:

Diagnostics Check	Type	Severity	Description
Orphan Owners	orphan_owner	warning	Active owners whose parent owner has closed or no longer exists.
Leaked Resources	leaked_resource	error	Tracked resources that were not released after their owner closed.
Suspended Fibers	suspended_fiber	warning	Fibers suspended in the event loop for longer than 10 seconds.
Stuck Executor	executor_stuck	error	Bounded execution units stuck without ticking.
Stuck Drain	drain_stuck	error	Process stuck in the draining state for more than 60 seconds.
Missing Extensions	missing_extension	warning	Missing optional recommended extensions (apcu, redis, mysqli, pgsql, zlib).

JSON Report Format:

{
  "timestamp": "2026-06-12T06:55:51+07:00",
  "healthy": false,
  "issues": [
    {
      "type": "leaked_resource",
      "severity": "error",
      "count": 1,
      "details": [
        {
          "resource_id": "184",
          "type": "db_connection",
          "owner_id": "req-9988",
          "age": 14.5,
          "created_at": 1718224516.5,
          "stack_trace": [ ... ]
        }
      ]
    },
    {
      "type": "missing_extension",
      "severity": "warning",
      "details": [
        {
          "extension": "redis",
          "optional": true
        }
      ]
    }
  ]
}

Related Guides

• Runtime Overview
• Observability
• Resource Lifecycle
• Ownership