Filament Spatie Laravel Health Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • UI Integration: Seamlessly integrates with Filament (Laravel admin panel), providing a dedicated health monitoring dashboard without requiring custom frontend development.
  • Leverages Spatie’s Health: Builds on spatie/laravel-health, a battle-tested package for application health checks (database, queues, cache, etc.), reducing reinvention.
  • Modular Design: Health checks are registerable via service providers, allowing granular control over monitored services.
  • Filament’s Ecosystem: Aligns with Filament’s resource-based architecture, making it easy to embed in existing admin panels.

• Cons:

  • Tight Coupling to Filament: If the team migrates away from Filament, this package may become obsolete or require refactoring.
  • Limited Customization: The UI is pre-built; deep customization (e.g., styling, layout) may require overriding Filament widgets or templates.

Integration Feasibility

• Dependencies:
  • Requires Laravel 10+, Filament 3.x, and spatie/laravel-health (v1.x).
  • No breaking changes in recent releases (last update: 2026-04-21), suggesting stability.
• Compatibility:
  • Works with any Laravel application using Filament for admin needs.
  • Health checks must be registered via Spatie’s package (e.g., DatabaseHealthCheck, QueueHealthCheck).
• Technical Risk:
  • Low to Medium:
    • Risk of Filament version conflicts if not aligned with the package’s supported versions.
    • Potential performance overhead if too many health checks are registered (though Spatie’s package is optimized).
  • Key Questions:
    • Are we using Filament 3.x? If not, will this require a migration?
    • Do we already use spatie/laravel-health? If not, will we need to adopt it alongside this package?
    • What health checks are critical for our application (e.g., third-party APIs, external services)?

Integration Approach

Stack Fit

• Ideal For:
  • Teams using Filament for admin panels and needing built-in health monitoring.
  • Applications where observability is critical but custom dashboards are not a priority.
• Non-Ideal For:
  • Projects not using Filament (would require alternative UI integration).
  • Teams needing real-time monitoring (this is a periodic check, not a live dashboard like Laravel Horizon).

Migration Path

1. Prerequisite Check:
   • Ensure Laravel 10+, Filament 3.x, and PHP 8.1+ are in use.
   • Verify Composer and Node.js (for Filament assets) are up to date.
2. Installation:

   composer require shuvroroy/filament-spatie-laravel-health
   

   • Publish config (if needed) via:

     php artisan vendor:publish --provider="ShuvroRoy\FilamentSpatieHealth\FilamentSpatieHealthServiceProvider"
     

3. Configuration:
   • Register health checks in App\Providers\AppServiceProvider (using Spatie’s syntax).
   • Example:

     use Spatie\Health\Checks\Checks\DatabaseHealthCheck;
     use Spatie\Health\Checks\Checks\QueueHealthCheck;
     
     public function boot(): void
     {
         Health::checks([
             DatabaseHealthCheck::new(),
             QueueHealthCheck::new(),
         ]);
     }
     

4. Access the Dashboard:
   • The health page will be available under Filament’s navigation (default: "Health" tab).

Compatibility

• Filament Plugins: Works alongside other Filament plugins (e.g., Filament Forms/Tables) without conflicts.
• Health Check Extensibility:
  • Can add custom checks by extending Spatie’s HealthCheck class.
  • Example:

    use Spatie\Health\Checks\HealthCheck;
    
    class CustomApiHealthCheck extends HealthCheck
    {
        public function performCheck(Result $result): void
        {
            $response = Http::get('https://api.example.com/health');
            if ($response->successful()) {
                $result->markAsHealthy();
            } else {
                $result->markAsUnhealthy();
            }
        }
    }
    

• Sequencing:
  • Install before deploying to production to avoid runtime surprises.
  • Test health checks in staging to ensure they don’t introduce false positives/negatives.

Operational Impact

Maintenance

• Pros:
  • Minimal Maintenance: The package is MIT-licensed and actively maintained (last release: 2026).
  • Centralized Logging: Health check results can be logged via Spatie’s HealthCheckLogger.
• Cons:
  • Dependency Updates: Must monitor Filament and Spatie Health for breaking changes.
  • Custom Checks: Any custom health checks require manual updates if Spatie’s API changes.

Support

• Troubleshooting:
  • Debugging Failed Checks: Use php artisan health:checks to run checks via CLI.
  • Filament Debugging: Leverage Filament’s debug tools if UI issues arise.
• Community:
  • Limited but Growing: 191 stars suggest moderate adoption; GitHub issues may not have immediate responses.
  • Spatie’s Ecosystem: Broader support available for spatie/laravel-health.

Scaling

• Performance:
  • Lightweight: Health checks run asynchronously by default (configurable).
  • Scaling Consideration: Heavy checks (e.g., database queries) may slow down Filament if run too frequently.
• Monitoring at Scale:
  • Can integrate with external monitoring tools (e.g., Datadog, Sentry) via Spatie’s HealthCheckLogger.
  • Example:

    Health::logger(function (Result $result) {
        Log::channel('sentry')->error('Health check failed', [
            'check' => $result->check->name(),
            'message' => $result->message(),
        ]);
    });
    

Failure Modes

Ramp-Up

• Onboarding Time: Low to Medium (1–2 days for basic setup).
  • For Developers:
    • Familiarity with Filament and Spatie packages accelerates adoption.
    • Documentation is clear but not exhaustive (may need to reference Spatie’s Health docs).
  • For Ops/DevOps:
    • Understand how to interpret health check results and set up alerts.
• Training Needs:
  • Health Check Design: Teach teams how to write reliable checks (e.g., avoid flaky external API calls).
  • Alerting: Integrate with PagerDuty, Slack, or email for critical failures.
• Key Metrics to Track:
  • Check Pass/Fail Rates: Identify recurring issues.
  • Dashboard Access Frequency: Gauge team engagement with observability.