Tweedegolf Prometheus Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: The package aligns with modern Laravel/Symfony observability needs by exposing Prometheus metrics (counters, gauges, histograms) for monitoring, logging, and alerting. However, Laravel’s ecosystem leans toward Laravel Telescope, Sentry, or Datadog for observability, making this a niche fit unless Prometheus is a strict requirement.
• Bundle vs. Standalone: As a Symfony bundle, it assumes Symfony’s dependency injection (DI) and kernel structure. Laravel’s Service Container and Facades differ, requiring abstraction layers (e.g., a custom facade or adapter) to integrate seamlessly.
• Metric Granularity: The package supports labeled metrics (e.g., url for request tracking), which is valuable for distributed tracing but may be overkill for lightweight Laravel apps.

Integration Feasibility

• Prometheus Client Dependency: Relies on tweedegolf/prometheus-client (v0.2.3, 2018), which is abandoned and lacks Laravel compatibility. The client’s API may not align with Laravel’s PSR-11 container or event-driven architecture.
• Configuration Overhead: Requires YAML-based configuration for collectors, routes, and storage adapters (e.g., APCU). Laravel’s config/ system supports YAML, but the bundle’s hardcoded Symfony assumptions (e.g., AppKernel) may conflict.
• Route Exposure: Exposes /metrics endpoint by default, which is standard for Prometheus but requires:
  • Middleware to restrict access (e.g., IP whitelisting).
  • CORS configuration if scraping remotely.
• Storage Adapters: Defaults to APCU (PHP cache), which is not persistent across server restarts. Laravel alternatives like Redis or database-backed adapters would need customization.

Technical Risk

• Deprecation Risk: The package and its core dependency are archived/unmaintained (last release: 2018). Security patches or Symfony 6+ compatibility are unlikely.
• Laravel-Specific Gaps:
  • No native support for Laravel’s events, queues, or Horizon (for queue metrics).
  • No integration with Laravel’s logging or monitoring services (e.g., Monolog handlers).
• Performance Impact: Metric collection adds overhead. Histograms (e.g., response_timing) require bucket calculations, which may slow down high-traffic endpoints.
• Testing Complexity: Mocking Prometheus metrics in Laravel’s Pest/PHPUnit tests would require custom test doubles due to the bundle’s tight coupling with Symfony components.

Key Questions

1. Why Prometheus?
   • Is Prometheus a hard requirement (e.g., corporate mandate), or are alternatives (e.g., Laravel Horizon metrics, Datadog, StatsD) viable?
2. Maintenance Commitment:
   • Can the team maintain a fork or wrapper to adapt this for Laravel?
   • Are there modern alternatives (e.g., spatie/laravel-prometheus)?
3. Metric Scope:
   • Which Laravel components need instrumentation? (e.g., HTTP requests, queues, database queries)
4. Storage Backend:
   • Is APCU acceptable, or is a Redis/Memcached adapter needed for persistence?
5. Security:
   • How will the /metrics endpoint be secured (e.g., basic auth, firewall rules)?

Integration Approach

Stack Fit

• Laravel Compatibility: Low due to Symfony-specific assumptions (e.g., AppKernel, CollectorRegistry service). A wrapper layer is required to:
  • Replace Symfony’s DI with Laravel’s Service Container.
  • Abstract route registration (Laravel uses Route::get() or API resources).
  • Adapt configuration from config.yml to Laravel’s config/prometheus.php.
• Alternative Stacks:
  • Symfony: Native fit (as intended).
  • Lumen: Similar to Laravel but with less DI complexity.
  • Legacy PHP: Possible with manual service registration.

Migration Path

1. Assessment Phase:
   • Audit existing monitoring tools (e.g., New Relic, Sentry) to identify gaps Prometheus would fill.
   • Benchmark alternatives like spatie/laravel-prometheus or prometheus/client_php.
2. Abstraction Layer:
   • Create a Laravel facade (e.g., Prometheus::counter('requests')->inc()) to hide Symfony-specific code.
   • Example:

     // app/Facades/Prometheus.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     class Prometheus extends Facade { protected static function getAccessor() { return 'prometheus'; } }
     

   • Register the bundle’s services manually in config/app.php:

     'prometheus' => function ($app) {
         return new \TweedeGolf\PrometheusBundle\PrometheusService($app);
     },
     

3. Configuration Adaptation:
   • Convert YAML config to Laravel’s config/prometheus.php:

     'collectors' => [
         'requests' => [
             'type' => 'counter',
             'labels' => ['url'],
             'help' => 'Number of requests',
         ],
     ],
     

   • Use Laravel’s Service Provider to bootstrap the bundle:

     // app/Providers/PrometheusServiceProvider.php
     public function register() {
         $this->app->register(\TweedeGolf\PrometheusBundle\TweedeGolfPrometheusBundle::class);
     }
     

4. Route Integration:
   • Register the /metrics route in routes/web.php:

     Route::get('/metrics', [\TweedeGolf\PrometheusBundle\Controller\MetricsController::class, 'metrics']);
     

   • Add middleware for security:

     Route::middleware(['throttle:60,1'])->get('/metrics', ...);
     

Compatibility

• PHP Version: The package targets PHP 7.1–7.2 (based on Symfony 4.x). Laravel 9+ supports PHP 8.0+, which may introduce BC breaks (e.g., named arguments, attributes).
• Symfony Components: Depends on symfony/dependency-injection, symfony/http-kernel, etc. These can be polyfilled but may add bloat.
• Storage Adapters: APCU is PHP-only. For Laravel, consider:
  • Redis: Use predis/predis as a drop-in replacement.
  • Database: Store metrics in a table with a custom adapter.

Sequencing

1. Phase 1: Proof of Concept
   • Instrument a single endpoint (e.g., API route) with basic counters.
   • Verify Prometheus can scrape metrics (curl http://laravel.test/metrics).
2. Phase 2: Core Metrics
   • Add request duration histograms and error counters.
   • Integrate with Laravel’s exception handler to track errors.
3. Phase 3: Advanced Use Cases
   • Custom collectors for queue jobs, database queries, or cache hits.
   • Alerting rules in Prometheus (e.g., alert if error_rate > 0.1).
4. Phase 4: Optimization
   • Benchmark performance impact.
   • Replace APCU with a distributed store (Redis) if needed.

Operational Impact

Maintenance

• Short-Term:
  • High effort to adapt the bundle for Laravel (abstraction layers, config migration).
  • Security patches: None expected from upstream; team must monitor tweedegolf/prometheus-client for vulnerabilities.
• Long-Term:
  • Forking risk: If the package breaks, the team must maintain a Laravel-compatible fork.
  • Dependency bloat: Symfony components may slow down Laravel’s lightweight footprint.
• Documentation:
  • Nonexistent for Laravel use. Team must document:
    • Custom facade usage.
    • Configuration quirks (e.g., storage adapter swaps).
    • Troubleshooting (e.g., metric collection failures).

Support

• Community: Zero support for Laravel. Issues would require reverse-engineering Symfony code.
• Debugging:
  • Prometheus metrics may not appear due to:
    • Incorrect service registration.
    • Storage adapter misconfiguration (e.g., APCU disabled).
    • Laravel’s caching interfering with metric persistence.
  • Logs: Limited debugging tools; may require dd() or Xdebug for Symfony-specific classes.
• Vendor Lock-in: Tight coupling to tweedegolf/prometheus-client makes migration to other clients difficult.

Scaling

• **Horizontal Sc