README

Full Documentation — Complete usage guide, configuration reference, and API docs.

🔍 Production-Grade Observability & APM for Laravel Applications

A lightweight, database-agnostic alternative to full APM tools, optimized specifically for Laravel apps. Features request tracing, performance profiling, slow query detection, OpenTelemetry/Prometheus integration, AI-based anomaly detection, and smart alerting.

✨ Features

Core Capabilities

• 📊 Request Tracing - Capture HTTP requests with route, controller, duration, memory usage, headers
• 🗄️ Database Query Monitoring - Track all queries, detect N+1 problems, identify slow queries
• ⚡ Performance Profiling - Per-route metrics, P50/P95/P99 latency, bottleneck identification
• 🐌 Slow Query Detector - Automatic detection with stack traces and optimization recommendations
• 🤖 AI Anomaly Detection - Statistical analysis (Z-score) to detect unusual patterns
• 📈 OpenTelemetry Export - OTLP protocol support for distributed tracing
• 📊 Prometheus Metrics - /metrics endpoint for Prometheus scraping
• 🔔 Smart Alerting - Slack/Telegram notifications with throttling and deduplication
• 🎨 Built-In Dashboard UI + API - Authenticated web dashboard at /admin/observability plus API endpoints for custom implementations
• 🗃️ Database Agnostic - Works with MySQL, PostgreSQL, SQLite, SQL Server

📦 Installation

1. Install via Composer

composer require rylxes/laravel-observability

2. Run Installation Command

php artisan observability:install

This will:

• Publish configuration file to config/observability.php
• Run migrations (creates observability tables)
• Display middleware setup instructions

3. Register Middleware

Add to app/Http/Kernel.php (Laravel 10) or bootstrap/app.php (Laravel 11):

Laravel 10:

protected $middleware = [
    // ... other middleware
    \Rylxes\Observability\Middleware\RequestTracingMiddleware::class,
];

Laravel 11:

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Rylxes\Observability\Middleware\RequestTracingMiddleware::class);
})

4. Configure Environment

Add to .env:

OBSERVABILITY_ENABLED=true
OBSERVABILITY_TRACING_ENABLED=true
OBSERVABILITY_SLOW_QUERY_THRESHOLD=1000

# Optional: Slack Notifications
OBSERVABILITY_SLACK_ENABLED=true
OBSERVABILITY_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Optional: Telegram Notifications
OBSERVABILITY_TELEGRAM_ENABLED=true
OBSERVABILITY_TELEGRAM_BOT_TOKEN=your_bot_token
OBSERVABILITY_TELEGRAM_CHAT_ID=your_chat_id

# Optional: Prometheus
OBSERVABILITY_PROMETHEUS_ENABLED=true

🚀 Usage

Using the Facade

use Rylxes\Observability\Facades\Observability;

// Get performance analysis
$analysis = Observability::analyze(days: 7);

// Detect slow queries
$slowQueries = Observability::slowQueries()->analyze();

// Detect anomalies
$anomalies = Observability::anomalies()->detectAnomalies('response_time');

// Export Prometheus metrics
$metrics = Observability::exportMetrics();

Artisan Commands

Analyze Performance:

php artisan observability:analyze --days=7 --notify

Prune Old Data:

php artisan observability:prune --force

Web Dashboard (Authenticated)

By default, the package includes a web dashboard at:

/admin/observability

It uses your app's configured auth guards (observability.dashboard.guards), so it works with your existing login/session setup while still exposing the API for internal tools.

API Endpoints

All endpoints are prefixed with /api/observability:

Example:

curl http://yourapp.test/api/observability/metrics
curl http://yourapp.test/api/observability/dashboard | jq

⚙️ Configuration

Database Connection

By default, uses your app's default database connection. To use a separate database:

OBSERVABILITY_DB_CONNECTION=observability_db

Then configure the connection in config/database.php.

Request Tracing

'tracing' => [
    'enabled' => true,
    'capture_headers' => true,
    'capture_payload' => false, // Be careful with sensitive data
    'excluded_routes' => ['telescope.*', 'horizon.*'],
    'sample_rate' => 1.0, // 0.0 to 1.0 (1.0 = trace all)
],

Slow Query Detection

'queries' => [
    'enabled' => true,
    'log_all' => false, // Only log slow queries
    'slow_threshold_ms' => 1000,
    'detect_duplicates' => true, // N+1 detection
],

Anomaly Detection (AI)

'anomaly_detection' => [
    'enabled' => true,
    'z_score_threshold' => 3.0, // Standard deviations
    'min_data_points' => 100,
    'baseline_window_days' => 7,
],

Notifications

'notifications' => [
    'slack' => ['enabled' => true, 'webhook_url' => env('...')],
    'telegram' => ['enabled' => true, 'bot_token' => env('...')],
    'throttle' => [
        'enabled' => true,
        'window_minutes' => 15,
        'max_alerts_per_window' => 1,
    ],
],

Data Retention

'retention' => [
    'traces_days' => 7,
    'queries_days' => 7,
    'metrics_days' => 30,
    'alerts_days' => 30,
],

Dashboard UI

'dashboard' => [
    'enabled' => true,
    'route_prefix' => 'admin/observability',
    'middleware' => ['web'],
    'guards' => ['web', 'sanctum'],
    'refresh_interval_seconds' => 30,
],

📊 Integrations

Prometheus

Enable in .env:

OBSERVABILITY_PROMETHEUS_ENABLED=true
OBSERVABILITY_PROMETHEUS_STORAGE=redis # or 'memory', 'apc'

Configure Prometheus to scrape:

scrape_configs:
  - job_name: 'laravel-app'
    static_configs:
      - targets: ['yourapp.test']
    metrics_path: '/api/observability/metrics'

OpenTelemetry

OBSERVABILITY_OTEL_ENABLED=true
OBSERVABILITY_OTEL_ENDPOINT=http://localhost:4318

Grafana Dashboard

Import the included Grafana dashboard template:

# Coming soon - dashboard JSON in /docs folder

🤖 AI Anomaly Detection

The plugin uses statistical analysis (Z-score method) to detect anomalies:

1. Baseline Calculation: Analyzes last 7 days (configurable)
2. Statistical Analysis: Calculates mean and standard deviation
3. Anomaly Detection: Flags values > 3σ from baseline
4. Auto-Alerting: Creates alerts for critical anomalies

Monitored Metrics:

• Response time
• Memory usage
• Error rate
• Query execution time

Example:

$result = Observability::anomalies()->detectAnomalies('response_time');

if ($result['status'] === 'success') {
    foreach ($result['anomalies'] as $anomaly) {
        echo "Anomaly: {$anomaly['metric_name']} - ";
        echo "Value: {$anomaly['value']} (Baseline: {$anomaly['baseline']})";
        echo "Deviation: {$anomaly['deviation_percent']}%";
    }
}

📈 Performance Insights

Dashboard Data Structure

{
  "overall_metrics": {
    "total_requests": 12500,
    "avg_response_time_ms": 145.3,
    "p95_response_time_ms": 450,
    "p99_response_time_ms": 890,
    "avg_memory_mb": 28.5,
    "error_rate": 1.2
  },
  "route_performance": [
    {
      "route": "api.users.index",
      "requests": 3400,
      "avg_duration_ms": 89,
      "error_rate": 0.5
    }
  ],
  "bottlenecks": [
    {
      "type": "slow_routes",
      "severity": "warning",
      "data": ["api.reports.generate"]
    }
  ]
}

🔒 Security Considerations

• Sensitive Data: Disable capture_payload and capture_headers in production
• Authentication: All API endpoints require authentication by default
• Data Sanitization: Passwords, tokens automatically redacted
• Rate Limiting: Consider adding rate limits to metrics endpoints

🧪 Testing

Run tests:

composer test

Local Development Loop (Deploy Once)

cd ..
composer create-project laravel/laravel observability-sandbox
cd observability-sandbox
composer config repositories.observability '{"type":"path","url":"../Observability Plugin","options":{"symlink":true}}'
composer require rylxes/laravel-observability:@dev
php artisan observability:install
php artisan migrate

This lets you test package changes locally through /admin/observability, then ship one release after validation.

With coverage:

composer test-coverage

📊 Database Schema

The plugin creates 4 tables (with configurable prefix):

All tables use your app's database connection (MySQL, PostgreSQL, SQLite, SQL Server).

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for details.

📝 License

MIT License. See LICENSE file.

🙏 Credits

Built with ❤️ for the Laravel community by Sherriff Agboola.

• OpenTelemetry PHP: https://github.com/open-telemetry/opentelemetry-php
• Prometheus PHP: https://github.com/PromPHP/prometheus_client_php

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: rylxes@gmail.com

⭐ If you find this useful, please star the repository!