Prometheus Client Php Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: The package excels as a Prometheus instrumentation library for Laravel/PHP, enabling standardized metrics collection (counters, gauges, histograms, summaries) with multi-process support (critical for Laravel’s request/worker isolation).
• Laravel Ecosystem Synergy:
  • Integrates seamlessly with Laravel’s service container (via CollectorRegistry binding).
  • Complements existing monitoring tools like Laravel Telescope or Sentry for hybrid observability.
  • Supports HTTP endpoint exposure (e.g., /metrics) via middleware or route handlers.
• Storage Flexibility: Offers 5 adapters (Redis, Predis, APCu, APCng, In-Memory, PDO), allowing trade-offs between persistence, performance, and resource constraints.
  • Redis/Predis: Best for distributed Laravel deployments (e.g., queues, Horizon).
  • APCu/APCng: Lightweight for single-server setups (reduces external dependencies).
  • PDO: For database-backed persistence (e.g., SQLite/MySQL).

Integration Feasibility

• Low Friction:
  • Composer-ready with zero Laravel-specific boilerplate.
  • Middleware Integration: Can expose metrics via a dedicated route (e.g., Route::get('/metrics', fn() => $renderer->render(...))).
  • Service Provider: Bind CollectorRegistry to Laravel’s container for DI.
• Existing Laravel Patterns:
  • Events: Instrument business logic via Laravel events (e.g., job.processed).
  • Middleware: Track request latency/errors in HandleIncomingRequest.
  • Queues: Monitor job execution time with prometheus_client_php in HandleJobs.
• Prometheus Ecosystem:
  • PushGateway: Requires companion library (prometheus_push_gateway_php) for ephemeral jobs (e.g., Laravel Artisan commands).
  • Alerting: Works with Prometheus + Alertmanager for SLOs (e.g., laravel_job_duration_seconds > 5).

Technical Risk

Key Questions

1. Deployment Model:
   • Are you using shared-nothing (Redis) or shared-memory (APCu) architectures?
   • Do you need persistent metrics across restarts (Redis/PDO) or ephemeral (In-Memory)?
2. Scaling Needs:
   • Will metrics be consumed by Prometheus server or PushGateway?
   • What’s the expected label cardinality (e.g., route, user_id)?
3. Laravel-Specific:
   • Should metrics be scoped to tenants (e.g., SaaS)?
   • How will you correlate metrics with logs (e.g., trace IDs)?
4. Operational Trade-offs:
   • Can Redis/Predis failover be tolerated during outages?
   • What’s the TTL strategy for metrics (e.g., 15m vs. 5m)?

Integration Approach

Stack Fit

• Laravel Core:
  • Service Container: Bind CollectorRegistry in a service provider.
  • Middleware: Expose /metrics via PrometheusMetricsMiddleware.
  • Events: Instrument Illuminate\Queue\Events\JobProcessed.
• Queue Workers:
  • Use Redis adapter for Horizon/queue workers to aggregate metrics.
  • Example: Track laravel_job_duration_seconds histogram.
• Artisan Commands:
  • Use PushGateway (companion library) for ephemeral metrics.
• API/Gateway:
  • Instrument Illuminate\Http\Request lifecycle (e.g., http_request_duration_seconds).

Migration Path

1. Phase 1: Instrumentation
   • Add package to composer.json.
   • Create a metrics service provider to bind CollectorRegistry.
   • Instrument critical paths (e.g., API routes, jobs) with counters/histograms.
2. Phase 2: Exposure
   • Add a middleware to expose /metrics endpoint.
   • Configure Prometheus to scrape http://laravel-app/metrics.
3. Phase 3: Alerting
   • Define Prometheus rules for SLOs (e.g., error_rate > 0.01).
   • Integrate with Alertmanager or Laravel Notifications.

Compatibility

Sequencing

1. Start Small:
   • Instrument 1–2 high-value metrics (e.g., API latency, job failures).
   • Use In-Memory adapter for prototyping.
2. Scale Storage:
   • Migrate to Redis for distributed setups.
   • Benchmark APCu vs. Redis for single-server performance.
3. Optimize:
   • Tune bucket sizes for histograms (e.g., exponential buckets for latency).
   • Implement metric filtering (e.g., exclude dev environments).
4. Automate:
   • Add CI checks for metric schema validity.
   • Use Prometheus Relabeling to clean labels (e.g., drop instance if redundant).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor promphp/prometheus_client_php for PHP 8.3+ compatibility.
  • Update Predis/Redis if using advanced features.
• Schema Drift:
  • Avoid breaking changes to metric names/labels (immutable by design).
  • Use Prometheus record rules to derive stable metrics.
• Storage Management:
  • Redis: Monitor memory usage; set maxmemory-policy.
  • APCu: Configure apc.shm_size to avoid evictions.
  • PDO: Add indexes for high-write workloads.

Support

• Troubleshooting:
  • Missing Metrics: Check adapter configuration (e.g., Redis connection).
  • High Cardinality: Use prometheus --web.enable-labels-on-buckets to debug.
  • Scraping Failures: Verify /metrics returns 200 OK with valid Prometheus format.
• Community:
  • Active Slack channel (promphp) for PHP-specific issues.
  • GitHub issues for bugs (response time: ~24–48h for critical fixes).

Scaling

• Horizontal Scaling:
  • Redis: Shared state across Laravel workers; no scaling limits.
  • APCu: Single-server only; avoid for multi-instance setups.
  • PDO: Database becomes bottleneck; consider read replicas.
• Performance:
  • Redis Latency: ~1–5ms per metric write (benchmark with ab or k6).
  • APCu Overhead: ~0.1–0.5ms (faster but less scalable).
  • Histogram Buckets: Pre-allocate buckets to avoid runtime overhead.
• Cost:
  • Redis: ~$15/month for 3GB RAM (AWS ElastiCache).
  • APCu: Zero cost (uses PHP memory).

Failure Modes