docs: add observability page (#2315)

Author: alexandre-daubois

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.