Laravel Prometheus Laravel Package

Product Decisions This Supports

• Observability Roadmap: Enables integration with Prometheus/Grafana for real-time monitoring of Laravel application metrics (e.g., queue jobs, user counts, API performance). Aligns with initiatives to improve SRE visibility and reduce MTTR.
• Build vs. Buy: Buy—avoids reinventing Prometheus integration for Laravel, leveraging a battle-tested, maintained package with built-in support for Horizon/queues.
• Use Cases:
  • Performance Monitoring: Track queue job processing (failed/successful), API latency, or custom business metrics (e.g., active_users).
  • Alerting: Trigger alerts in Grafana/PagerDuty based on Prometheus metrics (e.g., queue_jobs_pending > 1000).
  • Cost Optimization: Monitor resource usage (e.g., database queries) to identify bottlenecks in serverless/Laravel Vapor deployments.
  • Compliance/Reporting: Export metrics for audits or internal dashboards (e.g., "Jobs processed per hour").
• Tech Debt Reduction: Replaces ad-hoc logging with standardized metrics, reducing reliance on manual instrumentation.

When to Consider This Package

• Adopt if:

  • Your Laravel app uses Horizon/queues and needs visibility into job processing.
  • You’re already using Prometheus/Grafana (or planning to) for observability.
  • You need lightweight, low-overhead metrics collection (no heavy agents like Datadog).
  • Your team lacks expertise to build a custom Prometheus exporter for Laravel.
  • You require conditional metrics (e.g., api_errors only for HTTP 5xx responses).

• Look elsewhere if:

  • You need distributed tracing (use OpenTelemetry instead).
  • Your stack is non-Laravel (e.g., Node.js, Python).
  • You require advanced sampling or custom query logic (Prometheus client libraries may offer more flexibility).
  • Security constraints prevent exposing /prometheus endpoints (consider middleware restrictions or internal Prometheus servers).
  • You’re on Laravel <11 or PHP <8.4 (package drops legacy support).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us instrument our Laravel app with Prometheus—think of it as ‘Google Analytics for infrastructure.’ We’ll get real-time dashboards for queue health, API performance, and custom business metrics (e.g., user activity), all without adding engineers. It integrates with Grafana, so we can set up alerts like ‘Notify me if queue jobs stall for >5 minutes.’ This reduces downtime and helps us optimize costs by spotting inefficiencies early. It’s a low-risk, high-reward move—like adding a ‘check engine’ light for our backend."

ROI:

• DevOps: Faster incident response (e.g., "Why are jobs failing?").
• Engineering: Reduces toil from manual logging/debugging.
• Product: Data-driven decisions (e.g., "Traffic spikes at 3 PM—scale up").

For Engineering:

*"This is a drop-in Prometheus exporter for Laravel that handles the heavy lifting:

• Out-of-the-box metrics: Queue job stats (Horizon/vanilla), HTTP response codes, custom gauges/counters.
• Zero config for basics: Just add Prometheus::addGauge('users')->value(fn() => User::count()) and expose /prometheus.
• Security: Supports middleware (e.g., API tokens) to restrict access.
• Future-proof: Actively maintained (Laravel 13+, PHP 8.4+), with contributions from the community.

Trade-offs:

• Not a full APM: Won’t replace tools like Laravel Telescope for deep debugging.
• Grafana required: You’ll need to set up Prometheus + Grafana for visualization (but we can template dashboards).

Next Steps:

1. Pilot: Add to a staging environment, expose metrics to a local Prometheus instance.
2. Dashboard: Build a Grafana dashboard for key metrics (e.g., queue_jobs_processed, api_latency).
3. Alerts: Configure Prometheus rules for critical thresholds (e.g., failed_jobs > 0)."*