Health Monitoring

Health monitoring using Spatie Health package and Laravel Telescope for debugging.

Overview

The health monitoring system provides:

Health check endpoints for load balancers and monitoring
Dashboard UI for manual inspection
Email notifications for failures (throttled)
Historical data stored in database

Quick Start

Check Health Status

# Via Artisan
./vendor/bin/sail artisan health:check

# Via HTTP
curl http://localhost/health

Access Dashboard

Navigate to /health-dashboard (requires authentication).

Health Checks

Configured Checks

Check	Purpose	Threshold
Database	PostgreSQL connectivity	-
Cache	Redis connectivity	-
Disk Space	Available storage	Warn: 70%, Fail: 90%
Optimized App	Laravel optimization status	Production only
Debug Mode	APP_DEBUG is false	Production only
Environment	APP_ENV matches expected	Production only

Check Results

Each check returns one of:

ok - Check passed
warning - Check passed with concerns
failed - Check failed

Endpoints

JSON Endpoint

GET /health

Response (200 OK):
{
  "finishedAt": "2025-11-14T17:30:00Z",
  "checkResults": [
    {"name": "Database", "status": "ok"},
    {"name": "Cache", "status": "ok"},
    {"name": "UsedDiskSpace", "status": "ok", "meta": {"used": "45%"}}
  ]
}

Response (503 Service Unavailable):
{
  "finishedAt": "2025-11-14T17:30:00Z",
  "checkResults": [
    {"name": "Database", "status": "failed", "message": "Connection refused"}
  ]
}

Dashboard

GET /health-dashboard

Visual dashboard showing:

All check statuses
Historical trends
Failure details

Configuration

Health Config

File: config/health.php

return [
    'result_stores' => [
        Spatie\Health\ResultStores\EloquentHealthResultStore::class => [
            'connection' => env('HEALTH_DB_CONNECTION', env('DB_CONNECTION')),
            'model' => Spatie\Health\Models\HealthCheckResultHistoryItem::class,
            'keep_history_for_days' => 1,
        ],
    ],

    'notifications' => [
        'enabled' => true,
        'notifications' => [
            Spatie\Health\Notifications\CheckFailedNotification::class => ['mail'],
        ],
        'notifiable' => Spatie\Health\Notifications\Notifiable::class,
        'throttle_notifications_for_minutes' => 60,
    ],
];

The notifiable is Spatie’s stock Notifiable — there is no custom class. The mail recipient comes from HEALTH_NOTIFICATION_EMAIL.

Environment Variables

# Notification email
HEALTH_NOTIFICATION_EMAIL=ops@example.com

# Database connection for health checks
HEALTH_DB_CONNECTION=pgsql

Laravel Telescope

Telescope Overview

Telescope provides debugging and monitoring for:

Requests
Commands
Jobs
Exceptions
Logs
Database queries
Cache operations
Mail
Notifications

Access

GET /telescope

Requires authentication in production.

Telescope Configuration

File: config/telescope.php

'enabled' => env('TELESCOPE_ENABLED', true),

'ignore_commands' => [
    //
],

'ignore_paths' => [
    'nova-api*',
],

Data Retention

Telescope data is pruned daily:

Keeps last 14 days
Preserves exception entries
Runs via scheduler

Schedule::command('telescope:prune --hours=336 --keep-exceptions')->daily()->onOneServer();

Observability Stack

Beyond health checks, the application ships with two observability tools.

Sentry

Error and performance monitoring via sentry/sentry-laravel.

Config: config/sentry.php

Environment:

SENTRY_LARAVEL_DSN=
SENTRY_TRACES_SAMPLE_RATE=0.1

Captures exceptions and traces from web requests and queued jobs.

Nightwatch

Application performance monitoring (Laravel Nightwatch). In staging/production the app streams events to a dedicated agent container (laravelphp/nightwatch-agent, defined in compose.yaml).

Environment:

NIGHTWATCH_TOKEN=
LOG_STACK=stderr,nightwatch

Event volume is trimmed by configureNightwatchFiltering() in AppServiceProvider, which rejects high-volume, low-value events (infrastructure table queries on jobs/cache/telescope_*/health history, the TestQueueJob and Telescope pending-updates jobs, and noisy scheduled commands like optimize and telescope:prune).

Source: backend/app/Providers/AppServiceProvider.php

Custom Health Checks

Creating a Check

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class AerTicketApiCheck extends Check
{
    public function run(): Result
    {
        try {
            $service = app(AerticketCabinetService::class);
            $service->testConnection();

            return Result::make()->ok('AerTicket API is accessible');

        } catch (\Exception $e) {
            return Result::make()
                ->failed("AerTicket API unreachable: {$e->getMessage()}");
        }
    }
}

Registering Check

use Spatie\Health\Facades\Health;

Health::checks([
    // ... existing checks
    AerTicketApiCheck::new(),
]);

Alerting

Email Notifications

When a check fails, CheckFailedNotification is sent over the mail channel to Spatie’s stock Notifiable, which routes to HEALTH_NOTIFICATION_EMAIL. Notifications are throttled to one per hour.

HEALTH_NOTIFICATION_EMAIL=ops@example.com

No custom notifiable class and no Slack channel are configured. Spatie supports a Slack channel out of the box if one is ever needed (see config/health.php).

Troubleshooting

Health Check Failing

Run check manually:

./vendor/bin/sail artisan health:check

Check specific service:

# Database
./vendor/bin/sail artisan tinker
>>> DB::connection()->getPdo();

# Cache
>>> Cache::get('test');

Dashboard Not Loading

Check authentication
Verify route registration
Check middleware configuration

Telescope Not Recording

Check TELESCOPE_ENABLED=true
Verify storage permissions
Check database migration ran

Docker Health Monitoring - Container health
Queue System - Queue monitoring