From 063d835f7478c8af10eece1e713d001928982b54 Mon Sep 17 00:00:00 2001
From: martijn <git@sexybiggetje.nl>
Date: Fri, 4 Jul 2025 14:17:34 +0200
Subject: [PATCH] Add README.md

---
 README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a41d207
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# PHP-Furnace
+
+Proof of concept in alpha stage.
+
+A near zero-dependency, PHP-FPM process profiler and live streaming dashboard. Designed for PHP 8.1+ using only standard libraries. It uses `/proc`, `gdb`, and Server-Sent Events to continuously trace live PHP-FPM processes but requires PHP to have pcntl extension to be enabled.
+
+---
+
+## 🚀 Features
+
+* Monitors all running PHP-FPM worker processes
+* Tracks:
+
+  * Memory usage
+  * CPU time and deltas
+  * Number of open file descriptors
+  * Number of threads
+  * Last handled request URI (via `$_SERVER['REQUEST_URI']`)
+  * Backtraces using GDB
+* Streams data live to the browser via SSE
+* Comes with a minimal HTML viewer
+* Logs data in newline-delimited JSON for later use
+
+---
+
+## 📦 Requirements
+
+* PHP 8.1 or later
+* Linux-based system (uses `/proc` and GDB)
+* `gdb` installed and executable by the current user
+* `pcntl` extension enabled
+
+```bash
+sudo apt install gdb
+```
+
+---
+
+## 🛠️ Setup
+
+1. Ensure `gdb` and `pcntl` are available
+2. Run the script:
+
+```bash
+php furnace.php
+```
+
+3. Open the live dashboard:
+
+```
+http://localhost:8123/
+```
+
+---
+
+## 📁 Output Location
+
+Log data is appended to:
+
+```
+/tmp/php-furnace/furnace-stream.log
+```
+
+Each event is streamed to the browser and formatted in JSON:
+
+```json
+{
+  "time": 1720043265,
+  "delta": 5,
+  "pid": 3410,
+  "calls": 3,
+  "cpu_time_ticks": 20199,
+  "cpu_delta": 15,
+  "memory_kb": 10240,
+  "threads": 1,
+  "fds": 23,
+  "request_uri": "/index.php",
+  "stack": ["#0 ...", "#1 ..."]
+}
+```
+
+---
+
+## 🧯 Troubleshooting
+
+* **No data in the browser**:
+
+  * Check `/tmp/php-furnace/furnace-stream.log` for entries
+  * Confirm PHP-FPM workers exist via `ps aux | grep php-fpm`
+  * Ensure `gdb` is installed and accessible without blocking
+
+* **GDB timeout**:
+
+  * Process may be idle or protected — increase timeout or skip slow PIDs
+