Weave Code
Laravel Health Laravel Package
spatie/laravel-health
Monitor your Laravel app’s health by registering configurable checks (disk space, queues, cache, etc.). Get warnings or failures and receive notifications via mail or Slack, with an easy API for adding custom checks and reporting status.
Check the health of your Laravel app
Frequently asked questions about Laravel Health
- How do I install and set up spatie/laravel-health in a Laravel 10.x project?
- Run `composer require spatie/laravel-health` and publish the config file with `php artisan vendor:publish --tag=health-config`. The package auto-registers checks and notifications, so no additional service provider bootstrapping is needed. Default thresholds and checks are preconfigured in `config/health.php`.
- Which built-in health checks does this package include, and can I customize their thresholds?
- The package includes checks for disk space, database connectivity, queue jobs, HTTP endpoints, and more. Thresholds (e.g., disk usage percentages) are fully customizable via methods like `warnWhenUsedSpaceIsAbovePercentage()` or `failWhenQueueJobsAreAbove()`. See the [documentation](https://github.com/spatie/laravel-health) for all available checks and their configuration options.
- Does spatie/laravel-health support custom health checks for my specific use case (e.g., third-party API monitoring)?
- Yes, you can create custom checks by implementing the `ShouldBeHealthy` interface. The package provides a `CustomCheck` class as a starting point. For example, you could monitor a payment processor API by extending `CustomCheck` and defining your own `isHealthy()` logic. Check the [extending checks section](https://github.com/spatie/laravel-health#extending-checks) in the docs.
- How do notifications work, and can I integrate with other channels like PagerDuty or Discord?
- Notifications are triggered when checks fail or warn, with built-in support for Slack and email. To add other channels (e.g., PagerDuty, Discord), extend the `NotificationChannel` interface and bind it in the service container. The package’s notification system is designed to be channel-agnostic, so integration is straightforward.
- What’s the best way to run health checks in production? Should I use a cron job or Oh Dear’s polling?
- For production, you can use a cron job to run checks periodically (e.g., every 5 minutes) or integrate with Oh Dear for automated, cloud-based monitoring. Oh Dear polls your `/health` endpoint, reducing server load. The package includes a `HealthCheck` facade to manually trigger checks if needed, but automated polling is recommended for reliability.
- Does spatie/laravel-health work with Laravel Forge or Valet, and are there any known conflicts?
- Yes, the package works seamlessly with Forge, Valet, and other Laravel hosting solutions. There are no known conflicts with popular packages like Laravel Horizon, Spatie’s other tools, or Forge/Valet-specific configurations. Always test in a staging environment first, especially if using custom checks or notifications.
- How do I store health check results, and can I avoid using a database for lightweight deployments?
- By default, results are stored in the database using `DatabaseHealthResultStore`. For lightweight deployments (e.g., Docker containers), use `InMemoryHealthResultStore`, which stores results temporarily in memory. Switch stores by configuring `health_result_store` in `config/health.php`. Note that in-memory storage won’t persist across restarts.
- Can I test health checks locally before deploying to production?
- Yes, you can manually trigger checks using the `Health::check()` method or by visiting the `/health` endpoint. For testing custom checks, use PHPUnit’s mocking capabilities to simulate failure scenarios. The package doesn’t include a dedicated testing helper, but you can assert check results using Laravel’s HTTP tests or unit tests.
- What’s the performance impact of running health checks, and how often should I run them?
- Health checks are designed to be lightweight, but performance depends on the checks themselves (e.g., HTTP endpoint checks may add latency). For most applications, running checks every 5–15 minutes is sufficient. Test under load with `UsedDiskSpaceCheck` or `DatabaseConnectionCheck` to gauge impact. Avoid running checks during peak traffic if they’re resource-intensive.
- Are there alternatives to spatie/laravel-health for Laravel health monitoring, and how does this compare?
- Alternatives include `spatie/laravel-monitor` (simpler, less extensible) and `laravel-debugbar/healthcheck` (basic checks only). This package stands out for its threshold-based alerts, notification flexibility, and Oh Dear integration. Unlike `laravel-debugbar`, it’s production-focused, and unlike `spatie/laravel-monitor`, it supports custom checks and multiple notification channels out of the box.
Weaver
How can I help you explore Laravel packages today?