junixlabs/laravel-observatory

Observability toolkit for Laravel applications - Monitor HTTP requests, outbound calls, queue jobs with Prometheus and SidMonitor support

v1.1.0 2025-12-25 05:09 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/queue: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• promphp/prometheus_client_php: ^2.6

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• phpstan/phpstan: ^1.10|^2.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• JunixLabs

• logging
• monitoring
• Metrics
• laravel
• apm
• prometheus
• tracing
• observability

README

A comprehensive observability toolkit for Laravel applications. Monitor HTTP requests, outbound API calls, queue jobs, and exceptions with Prometheus metrics export.

Features

• Inbound Request Monitoring - Automatically track all incoming HTTP requests
• Outbound HTTP Monitoring - Monitor all HTTP client calls to external services
• Queue Job Monitoring - Track job execution, duration, and failures
• Exception Tracking - Capture and count application exceptions
• Prometheus Export - Native Prometheus metrics format with /metrics endpoint
• SidMonitor Integration - (Coming Soon) Advanced monitoring with SidMonitor platform
• Custom Metrics - Add your own counters, gauges, and histograms
• Zero Configuration - Works out of the box with sensible defaults

Requirements

• PHP 8.2+
• Laravel 10.0+, 11.0+, or 12.0+

Installation

composer require junixlabs/laravel-observatory

The package will auto-register its service provider.

Publish Configuration (Optional)

php artisan vendor:publish --tag=observatory-config

Quick Start

After installation, Observatory automatically:

1. Monitors all incoming HTTP requests
2. Tracks outbound HTTP calls via Laravel's HTTP client
3. Monitors queue job execution
4. Exposes metrics at /metrics endpoint

Visit http://your-app.test/metrics to see your Prometheus metrics!

Configuration

Basic Configuration

# Enable/disable Observatory
OBSERVATORY_ENABLED=true

# Your application name (used in metrics)
OBSERVATORY_APP_NAME=my-app

# Exporter: 'prometheus' or 'sidmonitor'
OBSERVATORY_EXPORTER=prometheus

Prometheus Configuration

# Metrics endpoint path
OBSERVATORY_PROMETHEUS_ENDPOINT=/metrics

# Storage: 'memory', 'redis', 'apc', 'apcu'
OBSERVATORY_PROMETHEUS_STORAGE=memory

# Redis configuration (if using redis storage)
OBSERVATORY_REDIS_HOST=127.0.0.1
OBSERVATORY_REDIS_PORT=6379

# Enable basic auth for metrics endpoint
OBSERVATORY_PROMETHEUS_AUTH_ENABLED=false
OBSERVATORY_PROMETHEUS_AUTH_USERNAME=prometheus
OBSERVATORY_PROMETHEUS_AUTH_PASSWORD=secret

Feature Toggles

# Inbound request monitoring
OBSERVATORY_INBOUND_ENABLED=true

# Outbound HTTP monitoring
OBSERVATORY_OUTBOUND_ENABLED=true

# Queue job monitoring
OBSERVATORY_JOBS_ENABLED=true

# Exception tracking
OBSERVATORY_EXCEPTIONS_ENABLED=true

Prometheus Metrics

Available Metrics

Metric	Type	Description
{app}_http_requests_total	Counter	Total HTTP requests by method, route, status
{app}_http_request_duration_seconds	Histogram	Request latency distribution
{app}_http_outbound_requests_total	Counter	Outbound HTTP requests by method, host, status
{app}_http_outbound_duration_seconds	Histogram	Outbound request latency
{app}_jobs_processed_total	Counter	Queue jobs by name, queue, status
{app}_jobs_duration_seconds	Histogram	Job execution duration
{app}_exceptions_total	Counter	Exceptions by class and file

Prometheus Configuration

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'laravel'
    static_configs:
      - targets: ['your-app.test:80']
    metrics_path: '/metrics'
    # If using basic auth:
    # basic_auth:
    #   username: 'prometheus'
    #   password: 'secret'

Custom Metrics

Use the Observatory facade to add custom metrics:

use JunixLabs\Observatory\Facades\Observatory;

// Increment a counter
Observatory::increment('api_calls', ['endpoint' => 'users']);

// Set a gauge value
Observatory::gauge('active_connections', 42, ['server' => 'web-1']);

// Record a histogram observation
Observatory::histogram('payment_amount', 99.99, ['currency' => 'USD']);

Excluding Paths and Jobs

Exclude Paths from Monitoring

In config/observatory.php:

'inbound' => [
    'exclude_paths' => [
        'telescope*',
        'horizon*',
        '_debugbar*',
        'health',
        'metrics',
        'api/internal/*',
    ],
],

Exclude Jobs from Monitoring

'jobs' => [
    'exclude_jobs' => [
        'App\Jobs\InternalHealthCheck',
        'App\Jobs\MetricsCollection',
    ],
],

Exclude Hosts from Outbound Monitoring

'outbound' => [
    'exclude_hosts' => [
        'localhost',
        '127.0.0.1',
        'internal-service.local',
    ],
],

Storage Adapters

For production environments with multiple workers, use persistent storage:

Redis Storage (Recommended)

OBSERVATORY_PROMETHEUS_STORAGE=redis
OBSERVATORY_REDIS_HOST=127.0.0.1
OBSERVATORY_REDIS_PORT=6379

APCu Storage

OBSERVATORY_PROMETHEUS_STORAGE=apcu

SidMonitor Integration (Coming Soon)

SidMonitor provides advanced monitoring features beyond Prometheus:

• Real-time log streaming
• Distributed tracing
• Alerting and notifications
• Custom dashboards
• Rich contextual data

OBSERVATORY_EXPORTER=sidmonitor
OBSERVATORY_SIDMONITOR_ENDPOINT=https://api.sidmonitor.com
OBSERVATORY_SIDMONITOR_API_KEY=your-api-key
OBSERVATORY_SIDMONITOR_PROJECT_ID=your-project-id

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• JunixLabs
• All Contributors

License

The MIT License (MIT). Please see License File for more information.