Merge branch 'main' into fix/script_name

Author: henderkes

README.md

@@ -168,7 +168,7 @@ Go to `https://localhost`, and enjoy!
 - [Create **standalone**, self-executable PHP apps](https://frankenphp.dev/docs/embed/)
 - [Create static binaries](https://frankenphp.dev/docs/static/)
 - [Compile from sources](https://frankenphp.dev/docs/compile/)
-- [Monitoring FrankenPHP](https://frankenphp.dev/docs/metrics/)
+- [Observability](https://frankenphp.dev/docs/observability/)
 - [WordPress integration](https://frankenphp.dev/docs/wordpress/)
 - [Symfony integration](https://frankenphp.dev/docs/symfony/)
 - [Laravel integration](https://frankenphp.dev/docs/laravel/)

docs/logging.md

@@ -1,5 +1,8 @@
 # Logging
 
+> [!TIP]
+> Logging is one part of FrankenPHP's observability story. See the [Observability](observability.md) page for the full picture, including real-time monitoring and metrics.
+
 FrankenPHP integrates seamlessly with [Caddy's logging system](https://caddyserver.com/docs/logging).
 You can log messages using standard PHP functions or leverage the dedicated `frankenphp_log()` function for advanced
 structured logging capabilities.

docs/metrics.md

@@ -1,5 +1,8 @@
 # Metrics
 
+> [!TIP]
+> For a complete observability setup including real-time dashboards and production monitoring, see the [Observability](observability.md) page.
+
 When [Caddy metrics](https://caddyserver.com/docs/metrics) are enabled, FrankenPHP exposes the following metrics:
 
 - `frankenphp_total_threads`: The total number of PHP threads.

docs/observability.md

@@ -0,0 +1,35 @@
+# Observability
+
+FrankenPHP provides built-in observability features: [Prometheus-compatible metrics](metrics.md) and [structured logging](logging.md).
+These features, combined with the recommended tools below, give you full visibility into your PHP application's behavior in development and production.
+
+## Ember TUI and Prometheus Exporter
+
+[Ember](https://github.com/alexandre-daubois/ember) is the most user-friendly way to monitor FrankenPHP.
+
+It connects to Caddy's admin API and deeply integrates with FrankenPHP, providing real-time visibility with zero configuration and no external infrastructure.
+
+It is designed to be used in development and production, with a TUI dashboard for local use and a Prometheus export daemon mode for production monitoring.
+
+> [!TIP]
+> See the [Ember documentation](https://github.com/alexandre-daubois/ember) for the full list of features and setup details.
+
+## Metrics
+
+FrankenPHP exposes Prometheus-compatible metrics for threads, workers, request processing, and queue depth when [Caddy metrics](https://caddyserver.com/docs/metrics) are enabled.
+
+See the [Metrics](metrics.md) page for the full list of available metrics.
+
+## Logging
+
+FrankenPHP integrates with Caddy's logging system and provides `frankenphp_log()` for structured logging with severity levels and context data, making ingestion into platforms like Datadog, Grafana Loki, or Elastic straightforward.
+
+See the [Logging](logging.md) page for usage details.
+
+## Custom Prometheus/Grafana Setup
+
+If you prefer a custom monitoring stack, you can scrape FrankenPHP metrics directly.
+There are two options:
+
+1. **Scrape Caddy directly**: Caddy exposes metrics at its admin endpoint (default: `localhost:2019/metrics`)
+2. **Scrape via Ember**: when running Ember with `--expose`, it exposes FrankenPHP metrics along with computed metrics derived from Caddy data (RPS, latency percentiles, error rates) on a dedicated endpoint.

scaling.go

@@ -40,14 +40,17 @@ func initAutoScaling(mainThread *phpMainThread) {
 		return
 	}
 
+	done := mainThread.done
+	mstate := mainThread.state
+
 	scalingMu.Lock()
 	scaleChan = make(chan *frankenPHPContext)
 	maxScaledThreads := mainThread.maxThreads - mainThread.numThreads
 	autoScaledThreads = make([]*phpThread, 0, maxScaledThreads)
 	scalingMu.Unlock()
 
-	go startUpscalingThreads(maxScaledThreads, scaleChan, mainThread.done)
-	go startDownScalingThreads(mainThread.done)
+	go startUpscalingThreads(maxScaledThreads, scaleChan, done, mstate)
+	go startDownScalingThreads(done)
 }
 
 func drainAutoScaling() {
@@ -81,16 +84,16 @@ func addWorkerThread(worker *worker) (*phpThread, error) {
 }
 
 // scaleWorkerThread adds a worker PHP thread automatically
-func scaleWorkerThread(worker *worker) {
+func scaleWorkerThread(worker *worker, done chan struct{}, mstate *state.ThreadState) {
 	// probe CPU usage before acquiring the lock (avoids holding lock during 120ms sleep)
-	if !cpu.ProbeCPUs(cpuProbeTime, maxCpuUsageForScaling, mainThread.done) {
+	if !cpu.ProbeCPUs(cpuProbeTime, maxCpuUsageForScaling, done) {
 		return
 	}
 
 	scalingMu.Lock()
 	defer scalingMu.Unlock()
 
-	if !mainThread.state.Is(state.Ready) {
+	if !mstate.Is(state.Ready) {
 		return
 	}
 
@@ -111,16 +114,16 @@ func scaleWorkerThread(worker *worker) {
 }
 
 // scaleRegularThread adds a regular PHP thread automatically
-func scaleRegularThread() {
+func scaleRegularThread(done chan struct{}, mstate *state.ThreadState) {
 	// probe CPU usage before acquiring the lock (avoids holding lock during 120ms sleep)
-	if !cpu.ProbeCPUs(cpuProbeTime, maxCpuUsageForScaling, mainThread.done) {
+	if !cpu.ProbeCPUs(cpuProbeTime, maxCpuUsageForScaling, done) {
 		return
 	}
 
 	scalingMu.Lock()
 	defer scalingMu.Unlock()
 
-	if !mainThread.state.Is(state.Ready) {
+	if !mstate.Is(state.Ready) {
 		return
 	}
 
@@ -140,7 +143,7 @@ func scaleRegularThread() {
 	}
 }
 
-func startUpscalingThreads(maxScaledThreads int, scale chan *frankenPHPContext, done chan struct{}) {
+func startUpscalingThreads(maxScaledThreads int, scale chan *frankenPHPContext, done chan struct{}, mstate *state.ThreadState) {
 	for {
 		scalingMu.Lock()
 		scaledThreadCount := len(autoScaledThreads)
@@ -171,7 +174,7 @@ func startUpscalingThreads(maxScaledThreads int, scale chan *frankenPHPContext,
 
 			// if the request has been stalled long enough, scale
 			if fc.worker == nil {
-				scaleRegularThread()
+				scaleRegularThread(done, mstate)
 				continue
 			}
 
@@ -184,7 +187,7 @@ func startUpscalingThreads(maxScaledThreads int, scale chan *frankenPHPContext,
 				continue
 			}
 
-			scaleWorkerThread(fc.worker)
+			scaleWorkerThread(fc.worker, done, mstate)
 		case <-done:
 			return
 		}

scaling_test.go

@@ -20,7 +20,7 @@ func TestScaleARegularThreadUpAndDown(t *testing.T) {
 	autoScaledThread := phpThreads[1]
 
 	// scale up
-	scaleRegularThread()
+	scaleRegularThread(mainThread.done, mainThread.state)
 	assert.Equal(t, state.Ready, autoScaledThread.state.Get())
 	assert.IsType(t, &regularThread{}, autoScaledThread.handler)
 
@@ -48,7 +48,7 @@ func TestScaleAWorkerThreadUpAndDown(t *testing.T) {
 	autoScaledThread := phpThreads[2]
 
 	// scale up
-	scaleWorkerThread(workersByPath[workerPath])
+	scaleWorkerThread(workersByPath[workerPath], mainThread.done, mainThread.state)
 	assert.Equal(t, state.Ready, autoScaledThread.state.Get())
 
 	// on down-scale, the thread will be marked as inactive
@@ -69,7 +69,7 @@ func TestMaxIdleTimePreventsEarlyDeactivation(t *testing.T) {
 	autoScaledThread := phpThreads[1]
 
 	// scale up
-	scaleRegularThread()
+	scaleRegularThread(mainThread.done, mainThread.state)
 	assert.Equal(t, state.Ready, autoScaledThread.state.Get())
 
 	// set wait time to 30 minutes (less than 1 hour max idle time)