Getting Started

Minimal Setup

Installation:

composer require spatie/laravel-prometheus

Publish the config file:

php artisan vendor:publish --provider="Spatie\Prometheus\PrometheusServiceProvider"

Configuration: Edit config/prometheus.php to define:
- host (default: 127.0.0.1)
- port (default: 9256)
- metrics (enabled/disabled metrics like laravel, queue, cache, etc.)
First Use Case: Start the Prometheus server:
```
php artisan prometheus:server
```
Access metrics at http://localhost:9256/metrics. Verify Laravel-specific metrics (e.g., laravel_request_duration_seconds) appear in the output.

Where to Look First

Documentation: Spatie’s Laravel Prometheus Docs (covers setup, custom metrics, and integration).
Config File: config/prometheus.php (toggle metrics, adjust endpoints).
Metrics Endpoint: /metrics (validate data exposure).

Implementation Patterns

Core Workflows

Default Metrics: Automatically exposes:
- HTTP request metrics (status codes, duration, size).
- Queue metrics (job processing time, failures).
- Cache metrics (hit/miss ratios).
- Database metrics (query duration, count).
- Laravel-specific metrics (e.g., laravel_routes_count).

Custom Metrics: Use the PrometheusRegistrar facade to define custom metrics:

use Spatie\Prometheus\Facades\PrometheusRegistrar;

PrometheusRegistrar::gauge('my_app.custom_metric', 'Custom metric description');
PrometheusRegistrar::set('my_app.custom_metric', 42);

Conditional Metrics: Disable metrics in config/prometheus.php for performance-sensitive environments:
```
'metrics' => [
    'laravel' => env('APP_ENV') !== 'production',
    'queue'   => true,
],
```
Integration with Monitoring Tools:
- Point Prometheus to your Laravel app’s /metrics endpoint.
- Use Grafana for visualization (import pre-built Laravel dashboards from Grafana.com).

Advanced Patterns

Dynamic Metrics: Track dynamic values (e.g., user-specific metrics) using labels:

PrometheusRegistrar::gauge('user_activity', 'User activity count', ['user_id']);
PrometheusRegistrar::set('user_activity', ['user_id' => 123], 10);

Middleware for Request Metrics: Extend request tracking with middleware:

public function handle($request, Closure $next) {
    $start = microtime(true);
    $response = $next($request);
    $duration = microtime(true) - $start;

    PrometheusRegistrar::histogram('custom_request_duration_seconds')
        ->labels(['route' => $request->route()->getName()])
        ->observe($duration);

    return $response;
}

Health Checks: Expose a /health endpoint alongside /metrics to validate Prometheus connectivity:
```
Route::get('/health', function () {
    return response()->json(['status' => 'ok']);
});
```

Environment-Specific Config: Use environment variables to toggle metrics in .env:

PROMETHEUS_ENABLED=true
PROMETHEUS_METRICS="laravel,queue"

Then reference in config/prometheus.php:

'enabled' => env('PROMETHEUS_ENABLED', true),
'metrics' => explode(',', env('PROMETHEUS_METRICS', 'laravel,queue,cache')),

Gotchas and Tips

Common Pitfalls

Port Conflicts:
- Default port 9256 may clash with other services. Change in config/prometheus.php:
```
'port' => env('PROMETHEUS_PORT', 9257),
```
- Verify no firewall blocks the port:
```
sudo ufw allow 9257
```
Performance Overhead:
- Disable unnecessary metrics in production to reduce CPU/memory usage.
- Monitor Prometheus server resource usage (htop or docker stats).
Metric Naming Collisions:
- Avoid naming custom metrics with prefixes like laravel_ or prometheus_ to prevent conflicts with built-in metrics.
- Use a unique namespace (e.g., myapp_custom_metric).
Prometheus Scraping Issues:
- Ensure Prometheus can reach the Laravel app’s /metrics endpoint (check CORS, auth, or network policies).
- Test scraping manually:
```
curl http://localhost:9256/metrics
```

Debugging Tips

Log Metric Updates: Enable debug logging in config/prometheus.php:
```
'debug' => env('APP_DEBUG', false),
```
Check storage/logs/laravel.log for metric-related entries.

Validate Metric Exposure: Use curl to inspect raw metrics:

curl -v http://localhost:9256/metrics | grep "laravel_"

Prometheus Configuration: Validate prometheus.yml targets:

scrape_configs:
  - job_name: 'laravel'
    static_configs:
      - targets: ['laravel-app:9256']

Restart Prometheus after changes:

prometheus --config.file=prometheus.yml

Extension Points

Custom Metric Types: Extend beyond gauges/histograms by implementing Spatie\Prometheus\Metric\MetricInterface:
```
class CustomCounter implements MetricInterface {
    public function collect(): string { /* ... */ }
}
```
Register via PrometheusRegistrar::registerMetric().

Dynamic Metric Labels: Use closures for dynamic labels:

PrometheusRegistrar::gauge('dynamic_metric', function () {
    return ['user_id' => auth()->id()];
});

Prometheus Server Hooks: Override the server boot process in a service provider:

public function boot() {
    $this->app->make(Spatie\Prometheus\PrometheusServiceProvider::class)
        ->registerServer(function ($server) {
            $server->addCollector(new CustomCollector());
        });
}

Metric Aggregation: Use Prometheus’s built-in functions (sum, avg) to aggregate custom metrics in queries:
```
sum(laravel_request_duration_seconds_bucket{le="0.5"}) by (route)
```

Configuration Quirks

Environment Variables: Prefix config keys with PROMETHEUS_ for clarity:

PROMETHEUS_HOST=0.0.0.0
PROMETHEUS_PORT=9256

Access in config:

'host' => env('PROMETHEUS_HOST', '127.0.0.1'),

Docker Integration: Expose the port in docker-compose.yml:
```
services:
  laravel:
    ports:
      - "9256:9256"
```
Use links or Docker networks for Prometheus-Laravel communication.
Queue Worker Metrics: Ensure queue workers are running with the same Laravel environment (e.g., same .env) to expose consistent metrics.

Caching Metrics: Disable caching for /metrics in routes/web.php:

Route::get('/metrics', function () {
    return Spatie\Prometheus\Facades\PrometheusRegistrar::metrics();
})->middleware('throttle:60,1'); // Limit scraping rate

Laravel Prometheus Laravel Package