Prometheus Metrics Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Alignment: The bundle is natively designed for Symfony 5.4–8.x, making it a seamless fit for Laravel applications only if integrated via a Symfony microkernel or bridge (e.g., Symfony’s HttpKernel in a Laravel app). For pure Laravel, this requires a custom adapter layer to translate Symfony events (kernel.request, kernel.response) into Laravel’s middleware/container system.
• Prometheus Ecosystem: Leverages promphp/prometheus_client_php, a mature PHP Prometheus client, ensuring compatibility with existing Prometheus/Grafana stacks.
• Extensibility: Supports custom metrics collectors, storage backends (Redis/APCu), and label enrichment, aligning with Laravel’s modularity needs (e.g., custom middleware for metrics).

Integration Feasibility

• Symfony Dependency: High risk for Laravel due to Symfony-specific event system (EventDispatcher). Requires:
  • Middleware translation: Map Symfony’s RequestEvent/ResponseEvent to Laravel’s middleware pipeline.
  • Service container bridging: Use Laravel’s ServiceProvider to register Symfony’s CollectorRegistry and bundle services.
• Prometheus Client: The underlying promphp/prometheus_client_php is PHP-agnostic, so integration is feasible but requires manual wiring of collectors to Laravel’s event system (e.g., Illuminate\Http\Kernel events).
• Storage Backends: Redis/APCu support is directly usable in Laravel, but configuration must account for Laravel’s caching system (e.g., Redis via predis or php-redis).

Technical Risk

Key Questions

1. Symfony vs. Laravel Tradeoffs:
   • Is the team willing to adopt a Symfony microkernel for metrics, or must integration be pure Laravel?
   • Can we use Laravel’s Event system to replicate Symfony’s kernel.* events?
2. Storage Backend:
   • Should we use Redis (shared with Laravel’s cache/queue) or APCu (simpler but less scalable)?
   • How will metrics persist across Laravel’s request lifecycle (e.g., during queue jobs)?
3. Custom Metrics:
   • What Laravel-specific metrics are critical (e.g., Eloquent queries, queue jobs, API rate limits)?
   • Can we extend the bundle’s MetricsCollectorInterface to support Laravel’s ServiceContainer?
4. Observability Stack:
   • Will Prometheus metrics replace or complement existing monitoring (e.g., Laravel Telescope, Sentry)?
   • How will we visualize Laravel-specific metrics in Grafana (e.g., queue depth, cache hits)?

Integration Approach

Stack Fit

• Core Compatibility:
  • Laravel 10.x/11.x: PHP 8.2+ aligns with the bundle’s PHP support.
  • Symfony Bridge: Requires Symfony HttpKernel (e.g., symfony/http-kernel) or a custom event dispatcher to translate Laravel events to Symfony’s kernel.*.
  • Prometheus Client: promphp/prometheus_client_php is Laravel-agnostic; integration depends on event wiring.
• Storage Backends:
  • Redis: Native support in Laravel (predis/php-redis); ideal for shared metrics storage.
  • APCu: Requires APCu extension (less common in Laravel deployments).
  • In-Memory: Suitable for single-process apps (e.g., local dev).

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Install the bundle in a Symfony microkernel alongside Laravel (e.g., via Laravel\SymfonyBridge).
   • Test basic metrics collection (HTTP requests, responses).
   • Validate Grafana dashboard compatibility.
2. Phase 2: Laravel Integration
   • Option A (Symfony Bridge):
     • Use symfony/http-kernel to wrap Laravel’s Application in a Symfony kernel.
     • Register the bundle in Symfony’s AppKernel.
   • Option B (Custom Middleware):
     • Build middleware to dispatch Symfony events (e.g., kernel.request → Laravel’s booted event).
     • Manually wire CollectorRegistry to Laravel’s container.
3. Phase 3: Customization
   • Implement Laravel-specific collectors (e.g., for Illuminate\Queue, Illuminate\Database).
   • Extend storage backends (e.g., Laravel’s Redis cache as Prometheus storage).
   • Adapt Grafana dashboards for Laravel metrics (e.g., queue depth, job duration).

Compatibility

Sequencing

1. Step 1: Infrastructure Setup
   • Add artprima/prometheus-metrics-bundle and promphp/prometheus_client_php to composer.json.
   • Configure Redis or APCu as storage backend.
2. Step 2: Event System Bridge
   • Implement middleware to translate Laravel events to Symfony’s kernel.* (or vice versa).
   • Example: Dispatch kernel.request when Laravel’s Illuminate\Http\Request is processed.
3. Step 3: Metrics Collection
   • Enable default metrics (disable_default_metrics: false).
   • Test /metrics/prometheus endpoint.
4. Step 4: Custom Metrics
   • Create Laravel-specific collectors (e.g., for queue jobs, database queries).
   • Register collectors in services.yaml (via Laravel’s ServiceProvider).
5. Step 5: Visualization
   • Import Grafana dashboards and adapt for Laravel metrics.
   • Set up Prometheus scrape config (prometheus.yml).

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor artprima/prometheus-metrics-bundle for Symfony version drops (e.g., Symfony 5.4 EOL).
  • Risk: Laravel integration may break if Symfony dependencies change.
• Custom Code:
  • Event bridge middleware and custom collectors require maintenance as Laravel/Symfony evolve.
  • Storage backend (Redis/APCu) may need tuning for performance.
• Dependency Management:
  • promphp/prometheus_client_php is stable, but Laravel’s event system may drift from Symfony’s.

Support

• Debugging:
  • Symfony-specific issues (e.g., event dispatching) may require Symfony expertise.
  • Laravel integration gaps (e.g., missing collectors) need custom fixes.
• Community:
  • Limited Laravel-specific support; rely on Symfony/Prometheus communities.
• Tooling:
  • Use Laravel Telescope for debugging metrics collection.
  • Prometheus alerts for critical metrics (e.g., 5xx errors, queue backlog).

Scaling

• Horizontal Scaling:
  • Redis storage scales well across Laravel instances.
  • In-memory storage requires shared storage (e.g., Redis) for multi-process setups.
• Performance:
  • Metric collection overhead: Benchmark with 10k RPS to validate latency impact.
  • Storage bottlenecks: Redis memory usage may grow with high-cardinality labels.
• Resource Usage:
  • APCu: Limited by server memory.
  • Redis: Monitor memory