Laravel Prometheus Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: Fits seamlessly into Laravel’s ecosystem, leveraging Prometheus as a standardized metrics collection system. Aligns with modern observability stacks (e.g., Prometheus + Grafana).
• Extensibility: Supports custom metrics (gauges, counters) and pre-built collectors for Laravel queues/Horizon, enabling granular monitoring without reinventing the wheel.
• Laravel-Native: Integrates via service providers, facades, and middleware, minimizing architectural disruption.

Integration Feasibility

• Low Friction: Requires minimal setup (composer install, config publish, route registration). Pre-configured for common Laravel components (queues, Horizon).
• Middleware Support: Endpoint security (e.g., API token auth) can be enforced via Laravel’s middleware stack.
• Prometheus Compatibility: Exposes metrics in Prometheus’s native format (/metrics endpoint), ensuring compatibility with existing Prometheus setups.

Technical Risk

• Dependency Constraints: Requires PHP 8.4+ and Laravel 12+ (as of v1.5.0). Legacy stacks may need upgrades.
• Performance Overhead: Metrics collection adds minimal overhead, but high-frequency custom metrics could impact performance if not optimized (e.g., cached values).
• Security: Public /prometheus endpoint must be secured (e.g., IP whitelisting, auth middleware). Misconfiguration risks exposing sensitive metrics.
• Queue Collector Dependencies: Horizon collectors require Redis; vanilla queue collectors may need additional tuning for large-scale systems.

Key Questions

1. Stack Compatibility:
   • Does the target Laravel/PHP version meet the package’s requirements (PHP 8.4+, Laravel 12+)?
   • Are there existing Prometheus/Grafana integrations that could conflict or complement this package?
2. Metrics Scope:
   • Which custom metrics are critical (e.g., business KPIs, infrastructure metrics)? How will they be defined?
   • Should metrics be cached to reduce database/query overhead?
3. Security:
   • How will the /prometheus endpoint be secured (e.g., middleware, network policies)?
   • Are there sensitive metrics that should not be exposed?
4. Scaling:
   • How will metrics collection scale with traffic (e.g., distributed Laravel instances)?
   • Are there plans to extend monitoring to microservices or third-party APIs?
5. Maintenance:
   • Who will own metric definitions and alerts (e.g., SRE, DevOps)?
   • How will breaking changes (e.g., Laravel 13+) be managed?

Integration Approach

Stack Fit

• Laravel Ecosystem: Designed for Laravel, with native support for queues, Horizon, and Eloquent. Minimal boilerplate for custom metrics.
• Prometheus/Grafana: Seamless integration with Prometheus scrapers and Grafana dashboards. Pre-built dashboards (e.g., for queues) accelerate adoption.
• Observability Tools: Compatible with tools like Alertmanager, Thanos, or VictoriaMetrics for long-term storage/alerting.

Migration Path

1. Assessment Phase:
   • Audit current monitoring tools (e.g., New Relic, Datadog) to identify gaps this package fills.
   • Define critical metrics (e.g., queue depth, API latency, user counts).
2. Pilot Deployment:
   • Install in a staging environment with a subset of metrics (e.g., queue collectors).
   • Validate Prometheus scraping and Grafana visualization.
3. Full Rollout:
   • Gradually add custom metrics (e.g., business logic counters).
   • Secure the /prometheus endpoint (e.g., middleware, VPC restrictions).
4. Optimization:
   • Tune metric collection frequency (e.g., cache expensive queries).
   • Set up alerts in Prometheus/Grafana (e.g., queue backlog thresholds).

Compatibility

• Laravel Versions: Officially supports Laravel 12–13. Backward compatibility may require adjustments for older versions.
• PHP Extensions: Redis extension needed for Horizon collectors (not for vanilla queue metrics).
• Prometheus Client: Uses the prometheus/client_php library under the hood, ensuring standard compliance.
• Custom Code: Metrics defined via facades (Prometheus::addGauge()) or collectors are isolated from core logic.

Sequencing

1. Prerequisites:
   • Upgrade PHP/Laravel if necessary (e.g., to PHP 8.4+).
   • Install Prometheus server and configure scraping of the Laravel /prometheus endpoint.
2. Core Setup:
   • Publish config (php artisan vendor:publish --provider="Spatie\Prometheus\PrometheusServiceProvider").
   • Register the /prometheus route (or use middleware for security).
3. Collectors:
   • Enable built-in collectors (queues, Horizon) via config.
   • Add custom metrics in AppServiceProvider@boot() or dedicated collectors.
4. Visualization:
   • Import metrics into Grafana using the Prometheus data source.
   • Build dashboards for key metrics (e.g., queue latency, error rates).
5. Alerting:
   • Define alert rules in Prometheus (e.g., laravel_queue_jobs_pending > 100).
   • Integrate with alerting tools (e.g., Slack, PagerDuty).

Operational Impact

Maintenance

• Metric Ownership: Assign ownership of metric definitions to feature teams (e.g., "Auth team owns user_registration_count").
• Deprecation: Monitor Laravel/PHP version support (e.g., drop PHP 8.4 when unsupported).
• Documentation: Maintain a runbook for:
  • Adding/removing metrics.
  • Troubleshooting Prometheus scraping issues.
  • Upgrading the package (e.g., breaking changes in v1.5.0).

Support

• Troubleshooting:
  • Verify Prometheus can scrape the /prometheus endpoint (curl http://laravel-app/prometheus).
  • Check Laravel logs for collector errors (e.g., Redis connection issues).
  • Use Prometheus::flush() to debug metric values in development.
• Escalation Path:
  • For package bugs, open issues on GitHub.
  • For custom metric issues, engage the development team that owns the metric.

Scaling

• Horizontal Scaling:
  • Metrics are stateless; multiple Laravel instances can expose the same endpoint (Prometheus will aggregate).
  • Use collector_registry_wipe config to avoid duplicate metrics in clustered setups.
• Performance:
  • Cache expensive metric queries (e.g., User::count()) to avoid N+1 issues.
  • Limit high-frequency custom metrics (e.g., log metrics at 1-minute intervals).
• Distributed Systems:
  • For microservices, use Prometheus Federation or Thanos to aggregate metrics.
  • Tag metrics by service/environment (e.g., service="auth-service").

Failure Modes

Ramp-Up

• Onboarding:
  • Developers: Train on adding metrics via Prometheus::addGauge()/addCounter().
  • SREs: Configure Prometheus/Grafana and set up alerts.
• Training Materials:
  • Create a internal wiki with:
    • Quickstart guide (install, config, first metric).
    • Example dashboards for common use cases (queues, APIs).
    • Troubleshooting checklist.
• Adoption Metrics:
  • Track number of custom metrics added over time.
  • Measure alert coverage (e.g., % of critical metrics with alerts).
• Feedback Loop:
  • Gather input from teams on missing metrics (e.g., "We need DB connection pool metrics").
  • Iterate on dashboard templates based on usage patterns.