Download the PHP package iamfarhad/laravel-prometheus without Composer

🚀 Laravel Prometheus Metrics Package

Enterprise-grade Prometheus metrics exporter for Laravel applications with comprehensive monitoring capabilities and industry-standard SLO tracking.

Built on the official PromPHP/prometheus_client_php library for maximum compatibility and performance.

✨ Key Features

• 🎯 Complete Metric Types: Counter, Gauge, Histogram, and Summary metrics with percentile tracking
• 📊 Advanced Collectors: HTTP, Database, Cache, Queue, Commands, Events, Errors, Filesystem, Mail, and Horizon
• 🏭 Production-Ready: Built with official PromPHP library and Laravel best practices
• 📈 SLO Monitoring: Industry-standard bucket configurations for p50, p95, p99, p99.9 tracking
• 💾 Multiple Storage: Redis, Memory, and APCu storage adapters
• 🔒 Security First: IP whitelisting, authentication middleware, and secure endpoint protection
• ⚡ High Performance: Optimized for minimal overhead with intelligent filtering
• 🧪 Fully Tested: Comprehensive test suite covering all components
• 📝 Developer Friendly: Rich documentation and intuitive API

📦 Installation

Publish Configuration

HTTP Middleware Setup

For HTTP request tracking, you need to register the middleware. Choose one of these simple options:

✅ Option 1: Easy Helper (Recommended)

No more complex setup! Add this single line to your bootstrap/app.php:

Benefits:

• ✅ One line setup - No complex configuration needed
• ✅ Automatic checks - Only registers if HTTP collector is enabled
• ✅ Laravel 11+ optimized - Works perfectly with new bootstrap structure
• ✅ Future-proof - Handles configuration changes automatically

✅ Option 2: Manual Registration

✅ Option 3: Automatic Registration (Experimental)

Enable automatic middleware registration in your .env:

Note: Automatic registration attempts to register middleware programmatically. If it doesn't work in your setup, use Options 1 or 2.

⚡ Option 4: Route-Specific Registration (Performance Optimized)

For high-performance applications where you want to monitor only specific routes:

Route Groups:

Individual Routes:

Route Groups with Aliases:

Controller-Level Registration:

Conditional Route Monitoring:

Benefits of Route-Specific Registration:

• ✅ Performance: Monitor only critical endpoints
• ✅ Selective Monitoring: Focus on business-critical routes
• ✅ Resource Efficiency: Reduce monitoring overhead
• ✅ Environment Control: Different monitoring per environment
• ✅ Granular Control: Fine-tune monitoring scope

Use Cases:

• High-traffic applications with performance requirements
• API endpoints where you want selective monitoring
• Admin routes that need separate tracking
• Public vs authenticated route monitoring
• Critical business logic routes only

🚀 Quick Start

Basic Usage

Controller Integration

📊 Built-in Collectors

🌐 HTTP Request Collector

Automatically enabled - Tracks all HTTP requests with comprehensive metrics.

Metrics:

• http_requests_total{method, route, status} - Total HTTP requests counter
• http_request_duration_seconds{method, route} - Response time histogram
• http_request_duration_seconds_summary{method, route} - Response time percentiles
• http_request_size_bytes{method, route} - Request payload size
• http_response_size_bytes{method, route, status} - Response payload size

Industry-Standard Configuration:

Example Metrics:

🗄️ Database Query Collector

Automatically enabled - Monitors database performance with operation-level granularity.

Metrics:

• database_queries_total{connection, table, operation} - Query count by operation type
• database_query_duration_seconds{connection, table, operation} - Query duration histogram
• database_query_duration_seconds_summary{connection, table, operation} - Query duration percentiles

Supported Operations: select, insert, update, delete, create, drop, alter, truncate

Fine-Grained Configuration:

Example Metrics:

⚡ Cache Operation Collector

Disabled by default - Monitors application cache operations (not internal storage).

⚠️ Important: Disabled by default to prevent recursive counting of Prometheus's own Redis operations.

Metrics:

• cache_operations_total{store, operation, result} - Cache operation counts
• cache_operation_duration_seconds{store, operation} - Operation duration
• cache_operation_duration_seconds_summary{store, operation} - Duration percentiles

Operations: get, put, forget, flush
Results: hit, miss, success, failure

Intelligent Filtering:

Enable for Application Cache:

🔄 Queue Job Collectors

Basic Queue Collector

Automatically enabled - Tracks queue job processing and performance.

Metrics:

• queue_jobs_total{queue, connection, status, job_class} - Processed jobs count
• queue_job_duration_seconds{queue, job_class} - Job processing time histogram
• queue_job_duration_seconds_summary{queue, job_class} - Processing time percentiles
• queue_active_jobs{queue, connection} - Currently active jobs gauge

Status Values: completed, failed, exception, timeout

Enhanced Queue Collector

Advanced monitoring with comprehensive queue health metrics:

Additional Metrics:

• queue_job_wait_time_seconds{queue, job_class} - Time jobs wait before processing
• queue_job_retries_total{queue, job_class, reason} - Job retry attempts
• queue_job_timeouts_total{queue, job_class} - Job timeout occurrences
• queue_size{queue, connection, status} - Queue depth metrics
• queue_pending_jobs{queue, connection} - Jobs waiting to be processed
• queue_failed_jobs{queue, connection} - Failed jobs count
• queue_workers{queue, connection, supervisor} - Active worker processes

Configuration:

🎯 Command Collector

Automatically enabled - Tracks Laravel Artisan command executions.

Metrics:

• artisan_commands_total{command, status} - Command execution count
• artisan_command_duration_seconds{command, status} - Execution time histogram

Status Values: success, error, invalid_usage, interrupted, unknown

Configuration:

Example Metrics:

🌊 Horizon Collector

Available when Laravel Horizon is installed - Comprehensive Horizon monitoring.

Metrics:

• horizon_supervisors{environment} - Active supervisors count
• horizon_workload{queue, supervisor} - Queue workload distribution
• horizon_master_loops_total{environment} - Master supervisor loops
• queue_workers{queue, connection, supervisor} - Worker process tracking

Enable:

Features:

• ✅ Automatic Horizon detection
• ✅ Supervisor health monitoring
• ✅ Worker process tracking
• ✅ Workload balance analysis

🚨 Error Collector

Disabled by default - Tracks application errors and exceptions.

Metrics:

• application_errors_total{exception_class, severity, component} - Application errors
• application_response_errors_total{http_status, method, route} - HTTP errors
• application_critical_errors_total{exception_class, component} - Critical errors

📁 Additional Collectors

Event Collector

• events_fired_total{event_class, status} - Laravel event tracking

Filesystem Collector

• filesystem_operations_total{disk, operation, status} - File system operations

Mail Collector

• mail_sent_total{driver, status, template} - Email delivery tracking

Enable any collector:

⚙️ Configuration

Storage Backends

Choose your preferred storage backend:

Global Namespace

Set a global namespace to avoid metric name conflicts:

Results in metrics like: myapp_http_requests_total

Industry-Standard Defaults

The package comes with optimized industry-standard configurations:

🔒 Security

Protecting the Metrics Endpoint

The package automatically registers a /metrics endpoint with configurable security:

IP Address Restriction

Use the built-in AllowIps middleware:

Environment Configuration:

Features:

• ✅ IPv4 and IPv6 support
• ✅ CIDR notation support
• ✅ Multiple IP ranges
• ✅ Returns 403 for unauthorized access

Authentication

Add authentication middleware:

Combined Security

For maximum security:

🔧 Advanced Usage

Custom Metrics with Summary Support

Middleware Integration

Create custom middleware for application-specific metrics:

📈 Monitoring & Alerting

Prometheus Configuration

Add this scrape configuration to your prometheus.yml:

Essential Queries

SLO Monitoring

Database Performance

Queue Health

Grafana Dashboard

Create comprehensive dashboards with:

Panels:

• HTTP request rate and latency percentiles
• Database query performance by operation
• Queue processing metrics and health
• Error rates and exception tracking
• Command execution monitoring

Alerts:

• High error rate (> 1%)
• Slow database queries (p95 > 500ms)
• Queue depth growth
• Failed job rate increase

🧪 Testing

Test Suite Coverage

The package includes comprehensive tests:

• ✅ Unit Tests: All metric types and collectors
• ✅ Feature Tests: HTTP endpoints and middleware
• ✅ Integration Tests: Storage adapters and PromPHP integration
• ✅ Security Tests: IP filtering and authentication

Testing Custom Metrics

🚀 Performance Optimization

Best Practices

1. Enable Only Needed Collectors

2. Optimize Storage Backend

3. Configure Appropriate Buckets

4. Monitor Resource Usage

   • Each enabled collector adds minimal overhead (~0.1ms per request)
   • Summary metrics use more memory than histograms
   • High-cardinality labels increase storage requirements
5. Choose the Right Middleware Strategy

Middleware Performance Guide

Choose your middleware registration strategy based on your application requirements:

Performance Impact Comparison:

Real-World Example:

Memory Optimization

🔧 Troubleshooting

Common Issues

1. Cache Collector Showing False Metrics

   • Solution: Cache collector is disabled by default to prevent counting Prometheus's own Redis operations
   • Enable only for application cache: Ensure you're using dedicated cache stores

2. High Memory Usage

   • Use Redis storage instead of Memory
   • Reduce histogram bucket count
   • Optimize Summary quantiles and max age

3. Metrics Not Appearing

   • Check collector configuration in config/prometheus.php
   • Verify storage backend connectivity
   • Check Laravel logs for errors
4. Slow Response Times
   • Optimize histogram bucket configuration
   • Use Redis with proper connection pooling
   • Consider metric sampling for very high traffic

Debug Mode

Enable comprehensive debug logging to troubleshoot metrics collection:

Debug Output Examples:

Debug Features:

• ✅ Metric Operations: All metric registrations and operations
• ✅ Collector Activity: Detailed collector behavior tracking
• ✅ Performance Timing: Collection and rendering performance
• ✅ Storage Operations: Redis/storage adapter interactions
• ✅ Request Tracking: HTTP middleware execution flow
• ✅ Cache Filtering: Cache operation filtering logic

Production Note: Always disable debug mode in production to avoid log bloat.

Middleware Configuration

All available environment variables for easy configuration:

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development Setup

📄 License

This package is open-sourced software licensed under the MIT license.

🌟 Support

• 📖 Documentation: Laravel Prometheus Docs
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ⭐ Star on GitHub: Show your support

🏆 Credits

• Author: Farhad Zand
• Built on: PromPHP/prometheus_client_php
• Inspired by: Prometheus community best practices and Laravel ecosystem

🚀 Built with ❤️ for the Laravel community

Ready for enterprise-grade monitoring with industry-standard SLO tracking! ⭐

🎯 Key Differentiators

• ✅ Official PromPHP Integration: Built on the official PHP client
• ✅ Industry-Standard Buckets: Optimized for real-world SLO monitoring
• ✅ Complete Metric Types: Counter, Gauge, Histogram, AND Summary with percentiles
• ✅ Intelligent Filtering: Prevents recursive metric counting issues
• ✅ Security-First: Built-in IP filtering and authentication support
• ✅ Production-Ready: Used in enterprise Laravel applications
• ✅ Comprehensive Testing: Extensive test coverage for reliability
• ✅ Developer-Friendly: Rich documentation and intuitive API