Laravel Prometheus Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: The package aligns perfectly with modern Laravel observability needs, integrating seamlessly with Prometheus (a CNCF-standard monitoring tool) and Grafana for visualization. It bridges the gap between Laravel’s ecosystem and the broader observability stack, enabling metrics-driven decision-making.
• Extensibility: Supports custom metrics (gauges, counters, histograms) alongside built-in collectors for queues (Horizon/vanilla) and failed jobs. This modularity allows TPMs to prioritize metrics based on business criticality (e.g., queue depth, job failures, or custom business KPIs).
• Laravel-Native: Leverages Laravel’s service container, facades, and middleware, reducing friction for teams already familiar with the framework. The /prometheus endpoint is idiomatic and integrates with Laravel’s routing system.

Integration Feasibility

• Low-Coupling Design: Metrics collection is decoupled from business logic, minimizing risk of performance degradation or side effects. The package uses Laravel’s event system (e.g., jobs.failed) for queue metrics, ensuring consistency.
• Dependency Constraints: Requires Laravel 12+ and PHP 8.4+, which may necessitate upgrades for legacy stacks. However, the package’s active maintenance (last release: 2026-04-27) ensures compatibility with future Laravel versions.
• Prometheus Ecosystem: Assumes Prometheus server is already configured (or will be), which may require coordination with DevOps/SRE teams. The package does not include Prometheus server management—only metric exposure.

Technical Risk

• Performance Overhead: Metrics collection adds minimal overhead (~1–5ms per request for gauges/counters), but high-frequency custom metrics (e.g., per-request tracking) could impact performance. Mitigation: Use conditional metrics (when()) or batch updates.
• Security Risks:
  • Endpoint Exposure: The /prometheus endpoint must be secured (e.g., IP whitelisting, auth middleware). The package supports middleware but requires explicit configuration.
  • Sensitive Metrics: Custom metrics (e.g., user counts) may expose PII if not sanitized. Mitigation: Use aggregate metrics (e.g., active_users) instead of raw data.
• Queue Collector Dependencies:
  • Horizon collectors require Redis; vanilla queue collectors depend on Laravel’s queue system.
  • Risk: Misconfigured collectors (e.g., stale Redis connections) could skew metrics. Mitigation: Monitor collector health via Prometheus alerts.

Key Questions for TPM

1. Observability Strategy:
   • Are we using Prometheus/Grafana already? If not, what’s the roadmap for adoption?
   • Which metrics are critical (e.g., queue depth, job failures) vs. nice-to-have (e.g., custom business metrics)?
2. Integration Scope:
   • Should we enable all built-in collectors (queues, failed jobs) or customize a subset?
   • Do we need histograms (e.g., request latency) or just gauges/counters?
3. Security & Compliance:
   • How will we secure the /prometheus endpoint? (e.g., VPC peering, API keys)
   • Are there GDPR/PII concerns with custom metrics? If so, how will we anonymize data?
4. Operational Readiness:
   • Who will own metric alerting (e.g., SLOs for queue processing time)?
   • How will we handle metric cardinality explosion (e.g., per-user metrics)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Ideal for Laravel apps (12+) using queues (Horizon/vanilla), events, or custom logic. Works alongside existing monitoring (e.g., Laravel Telescope, Sentry).
• Prometheus/Grafana: Assumes Prometheus is the primary time-series database. If using Datadog/New Relic, this package may require additional adapters.
• Cloud/Serverless:
  • AWS/GCP: Compatible with managed Prometheus (e.g., AWS Managed Service for Prometheus) or self-hosted.
  • Serverless (Vapor): Supported (see fix for Vapor in changelog), but may need custom middleware for auth.

Migration Path

1. Assessment Phase:
   • Audit current monitoring tools (e.g., New Relic, custom logs). Identify gaps (e.g., queue metrics, business KPIs).
   • Define metric ownership: Which teams (DevOps, Product) will consume these metrics?
2. Pilot Deployment:
   • Start with built-in collectors (queues, failed jobs) to validate integration.
   • Add 1–2 custom metrics (e.g., active_users, api_requests_per_minute).
3. Full Rollout:
   • Secure the /prometheus endpoint (e.g., add throttle middleware).
   • Configure Prometheus scrape jobs and Grafana dashboards.
4. Optimization:
   • Tune collector frequency (e.g., cache expensive queries like User::count()).
   • Set up alerts for critical metrics (e.g., queue_jobs_pending > 1000).

Compatibility

Sequencing

1. Prerequisites:
   • Upgrade to Laravel 12+ and PHP 8.4+ if needed.
   • Install Prometheus and Grafana (or ensure compatibility with existing setup).
2. Package Installation:

   composer require spatie/laravel-prometheus
   php artisan vendor:publish --provider="Spatie\Prometheus\PrometheusServiceProvider"
   

3. Configuration:
   • Enable collectors in config/prometheus.php:

     'collectors' => [
         Spatie\Prometheus\Collectors\QueueCollector::class,
         Spatie\Prometheus\Collectors\FailedRecentJobsCollector::class,
     ],
     

   • Secure the /prometheus route (e.g., add auth:api middleware).
4. Prometheus Scraping:
   • Configure Prometheus to scrape http://laravel-app/prometheus (e.g., every 15s).
5. Visualization:
   • Import Grafana dashboards (e.g., Laravel + Prometheus templates).

Operational Impact

Maintenance

• Package Updates: Low effort—follow Spatie’s release cycle (quarterly). Test upgrades in staging.
• Custom Metrics: Requires manual updates if business logic changes (e.g., User::count() query).
• Collector Tuning:
  • Queue Collectors: May need adjustments for high-volume queues (e.g., Redis connection pooling).
  • Failed Jobs: Retention window for FailedRecentJobsCollector is configurable (default: 1 hour).

Support

• Troubleshooting:
  • Missing Metrics: Verify collectors are registered and dependencies (e.g., Redis) are healthy.
  • High Latency: Check Prometheus scrape latency; optimize expensive custom metrics.
• Documentation: Comprehensive (spatie.dev/docs/laravel-prometheus) but assumes familiarity with Prometheus.
• Community: Active GitHub repo (283 stars, recent contributions). Spatie offers commercial support for enterprises.

Scaling

• Horizontal Scaling:
  • Metrics are stateless (except for queue collectors). Works with Laravel Horizon’s distributed workers.
  • Caveat: Custom metrics with shared state (e.g., Redis-backed counters) require synchronization.
• Performance:
  • Gauges/Counters: Minimal overhead (~1ms per metric).
  • Histograms: Higher overhead (~5–10ms per sample). Use sparingly.
  • Queue Collectors: Redis-bound; ensure Redis cluster can handle load.
• Alerting:
  • Prometheus rules can trigger alerts (e.g., queue_jobs_pending > 1000).
  • Recommendation: Start with basic alerts (e.g., job failures) before adding complex SLOs.

Failure Modes