Metrics

Tip

For a complete observability setup including real-time dashboards and production monitoring, see the Observability page.

When Caddy metrics are enabled, FrankenPHP exposes the following metrics:

• frankenphp_total_threads: The total number of PHP threads.
• frankenphp_busy_threads: The number of PHP threads currently processing a request (running workers always consume a thread).
• frankenphp_queue_depth: The number of regular queued requests.
• frankenphp_total_workers{worker="[worker_name]"}: The total number of workers.
• frankenphp_busy_workers{worker="[worker_name]"}: The number of workers currently processing a request.
• frankenphp_worker_request_time{worker="[worker_name]"}: The time spent processing requests by all workers.
• frankenphp_worker_request_count{worker="[worker_name]"}: The number of requests processed by all workers.
• frankenphp_ready_workers{worker="[worker_name]"}: The number of workers that have called frankenphp_handle_request at least once.
• frankenphp_worker_crashes{worker="[worker_name]"}: The number of times a worker has unexpectedly terminated.
• frankenphp_worker_restarts{worker="[worker_name]"}: The number of times a worker has been deliberately restarted.
• frankenphp_worker_queue_depth{worker="[worker_name]"}: The number of queued requests.

For worker metrics, the [worker_name] placeholder is replaced by the worker name in the Caddyfile, otherwise the absolute path of the worker file will be used.

FrankenPHP exposes a /frankenphp/threads endpoint through the Caddy admin API. It returns a JSON snapshot of all active PHP threads, useful for debugging and building observability tools.

curl -s http://localhost:2019/frankenphp/threads | jq .

The endpoint returns a JSON object with the following structure:

{
    "ThreadDebugStates": [
        {
            "Index": 0,
            "Name": "worker-/path/to/worker.php",
            "State": "ready",
            "IsWaiting": true,
            "IsBusy": false,
            "WaitingSinceMilliseconds": 1234,
            "CurrentURI": "",
            "CurrentMethod": "",
            "RequestStartedAt": 0,
            "RequestCount": 42,
            "MemoryUsage": 2097152
        }
    ],
    "ReservedThreadCount": 3
}

Each entry in ThreadDebugStates contains: