Laravel Prometheus Laravel Package

Technical Evaluation

Architecture Fit The movemoveapp/laravel-prometheus package extends Laravel’s observability capabilities by integrating Prometheus metrics collection via a Redis-backed storage layer. It aligns well with Laravel’s service container, event-driven architecture, and existing monitoring stacks (e.g., Prometheus, Grafana). The fork’s primary value lies in its backward-compatible support for predis/predis ^3.0, addressing a critical dependency gap in the original package. This makes it particularly relevant for Laravel applications leveraging Redis for caching, queues, or session storage, where Prometheus metrics need to be collected efficiently.

Integration Feasibility Integration is highly feasible with minimal friction for Laravel applications. The package leverages Laravel’s native service provider system, requiring only:

1. Composer dependency addition (movemoveapp/laravel-prometheus).
2. Service provider registration in config/app.php.
3. Optional configuration publishing (php artisan vendor:publish).
4. Redis client configuration (REDIS_CLIENT=predis in .env).

The lack of breaking changes in this release ensures zero-code migration for existing users of the original package. However, teams must explicitly opt into predis/predis ^3.0 support if using Redis, which may require dependency updates.

Technical Risk

• Low to Moderate:
  • Dependency Risk: The fork’s sole addition (predis/predis ^3.0 support) is optional and only relevant for Redis-dependent applications. Teams not using Redis face no technical risk.
  • Fork Stability: The package’s maturity (MIT license, active fork) and lack of code changes reduce risk, but the long-term maintenance of the fork by movemoveapp is unproven (0 stars, no dependents). Monitor for updates or consider the original package if stability is critical.
  • Redis Compatibility: Predis ^3.0 may introduce minor behavioral changes (e.g., API adjustments). Test thoroughly if migrating from ^2.0.
• Key Technical Debt:
  • Redis metrics storage adds indirect dependency on Redis infrastructure. Teams without Redis may prefer in-memory or file-based storage solutions.

Key Questions

1. Redis Dependency:
   • Does the application use Redis (predis/predis)? If so, is ^3.0 support a requirement (e.g., for new features) or preference (e.g., to future-proof)?
   • What is the current Redis client version (predis/predis ^2.0 or other)? Will upgrading to ^3.0 introduce compatibility risks?
2. Observability Strategy:
   • Are metrics currently collected via another tool (e.g., Laravel Telescope, StatsD)? How does this package complement or replace existing solutions?
   • Does the team have Prometheus/Grafana already integrated? If not, assess the effort to expose /metrics endpoint and visualize data.
3. Maintenance and Support:
   • Is movemoveapp’s long-term commitment to this fork acceptable? If not, consider the original package or alternatives like spatie/laravel-monitoring.
   • Are there existing CI/CD pipelines for monitoring tools? How will this package fit into them?
4. Performance:
   • What is the expected volume of metrics? Redis-backed storage may introduce latency for high-throughput applications.
   • Are there alternative storage backends (e.g., in-memory) that could reduce Redis dependency?
5. Customization:
   • Does the team need custom metric types (e.g., histograms, summaries) beyond counters/gauges? The package supports only these two types.
   • Are there existing metric classes that would need migration to the new package?

Integration Approach

Stack Fit The package is optimized for Laravel ecosystems and integrates seamlessly with:

• Laravel Core:
  • Service container (via PrometheusServiceProvider).
  • Artisan commands (make:counter, make:gauge) for metric generation.
  • Facade-based or dependency-injected metric usage.
• Redis Infrastructure:
  • Uses predis/predis for Redis-backed metrics storage (optional but recommended for scalability).
  • Requires Redis server and REDIS_CLIENT=predis in .env.
• Prometheus Ecosystem:
  • Exposes /metrics endpoint in Prometheus text format (default: /prometheus/metrics).
  • Compatible with Prometheus scrapers, Grafana, and other observability tools.
• Event-Driven Architecture:
  • Metrics can be instrumented in controllers, middleware, or events (e.g., AuthCounter for auth events).

Migration Path

1. Pre-Integration Assessment (1–2 hours):
   • Audit existing monitoring tools (e.g., Telescope, Datadog) for overlap.
   • Verify Redis usage and predis/predis version compatibility.
2. Dependency Update (30 minutes):

   composer require movemoveapp/laravel-prometheus
   composer require predis/predis:^3.0  # Only if using Redis
   

3. Configuration Setup (1 hour):
   • Register the service provider in config/app.php:

     Shureban\LaravelPrometheus\PrometheusServiceProvider::class,
     

   • Publish config (optional):

     php artisan vendor:publish --provider="Shureban\LaravelPrometheus\PrometheusServiceProvider"
     

   • Update .env:

     REDIS_CLIENT=predis
     

4. Metric Instrumentation (2–4 hours):
   • Generate custom metrics using Artisan:

     php artisan make:counter AuthEvents --name=auth_events --labels=event,user_type --description="Auth-related events"
     

   • Or manually create classes (e.g., app/Prometheus/AuthCounter.php).
   • Inject metrics into controllers/services:

     public function register(AuthCounter $authCounter) {
         $authCounter->withLabelsValues(['event' => 'registration'])->inc();
     }
     

5. Endpoint Exposure (30 minutes):
   • Ensure /prometheus/metrics is accessible (e.g., via Laravel routes or reverse proxy).
   • Test with curl http://localhost/prometheus/metrics.
6. Prometheus Integration (1–2 hours):
   • Add scrape config to prometheus.yml:

     scrape_configs:
       - job_name: 'laravel_app'
         static_configs:
           - targets: ['laravel-app:8000']
     

   • Verify metrics appear in Prometheus and Grafana.

Compatibility

• Laravel Versions: Tested with Laravel 11/12. Check compatibility with your version.
• Redis: Required only for Redis-backed storage. Non-Redis users can skip predis/predis and use alternative backends (if supported).
• Prometheus: Fully compatible with Prometheus 2.x/3.x.
• Alternatives: If Redis is undesirable, evaluate:
  • In-memory storage (e.g., symfony/cache).
  • File-based storage (e.g., prometheus/client_php).
  • Other Laravel packages like spatie/laravel-monitoring.

Sequencing

1. Phase 1: Non-Production Validation (1–2 days):
   • Deploy to staging/dev with a feature flag for metrics collection.
   • Test with realistic traffic to validate Redis performance (if used).
2. Phase 2: Metric Coverage Expansion (3–5 days):
   • Instrument critical paths (e.g., auth, payments, API endpoints).
   • Validate dynamic labels (e.g., user_id, country) for granularity.
3. Phase 3: Prometheus/Grafana Integration (1–2 days):
   • Set up scraping and dashboards.
   • Define alerts (e.g., error rate spikes).
4. Phase 4: Production Rollout (1 day):
   • Enable metrics in production with gradual rollout (e.g., canary).
   • Monitor /metrics endpoint and Redis latency (if applicable).

Operational Impact

Maintenance

• Effort: Low to Moderate
  • Pros:
    • No code changes in this release → zero maintenance overhead for existing users.
    • MIT license → no vendor lock-in.
  • Cons:
    • Fork Dependency: Relying on movemoveapp for updates. Monitor for:
      • Bug fixes (e.g., Predis ^3.0 issues).
      • Feature additions (e.g., new metric types).
    • Redis Dependency: If using Redis, monitor:
      • Predis ^3.0 updates for breaking changes.
      • Redis server performance under metrics load.
  • Recommendations:
    • Pin movemoveapp/laravel-prometheus to a specific version in composer.json to avoid unexpected updates.
    • Set up dependency alerts (e.g., GitHub watch, Dependabot) for predis/predis and the