federicozardi / laravel-health-check
A comprehensive health check package for Laravel applications with Kubernetes support
Installs: 366
Dependents: 0
Suggesters: 0
Security: 0
pkg:composer/federicozardi/laravel-health-check
Requires
- php: ^8.2
- illuminate/cache: ^10.0|^11.0|^12.0
- illuminate/database: ^10.0|^11.0|^12.0
- illuminate/http: ^10.0|^11.0|^12.0
- illuminate/support: ^10.0|^11.0|^12.0
- laravel/framework: ^10.0|^11.0|^12.0
- nesbot/carbon: ^2.0|^3.0
Requires (Dev)
- mockery/mockery: ^1.6
- orchestra/testbench: ^8.0|^9.0|^10.0
- phpunit/phpunit: ^10.0|^11.0
README
A comprehensive health check package for Laravel applications with Kubernetes support. This package provides standardized health check endpoints that are essential for monitoring, load balancing, and container orchestration.
Features
- Multiple Health Check Endpoints: Basic, detailed, storage-specific, liveness, and readiness probes
- Kubernetes Ready: Built-in support for Kubernetes liveness and readiness probes
- Configurable Checks: Enable/disable specific health checks based on your needs
- Custom Health Checks: Extend the package with your own health check implementations
- Storage Backend Monitoring: Monitor multiple storage backends (database, cache, custom)
- System Information: Include system resources, PHP/Laravel versions, and performance metrics
- Response Time Tracking: Measure and report health check response times
Installation
Via Composer
composer require federicozardi/laravel-health-check
Publish Configuration
php artisan vendor:publish --provider="Federicozardi\LaravelHealthCheck\Providers\HealthCheckServiceProvider" --tag="health-check-config"
Configuration
The package configuration file will be published to config/health-check.php. Here's an overview of the main configuration options:
return [
'checks' => [
'database' => true,
'cache' => true,
'storage' => false,
'system' => true,
],
'routes' => [
'prefix' => 'health',
'middleware' => ['api'],
'enabled' => [
'basic' => true,
'detailed' => true,
'storage' => false,
'liveness' => true,
'readiness' => true,
],
],
// ... more configuration options
];
Available Endpoints
Basic Health Check
GET /health
Returns basic service information and status.
Response:
{
"status": "healthy",
"name": "My Application",
"service": "my-service",
"environment": "production",
"version": "1.0.0",
"debug": false,
"timestamp": "2025-01-27T10:30:45.123Z",
"uptime": "running"
}
Detailed Health Check
GET /health/detailed
Returns comprehensive health information including database, cache, system info, and performance metrics.
Response:
{
"status": "healthy",
"timestamp": "2025-01-27T10:30:45.123Z",
"service": {
"name": "My Application",
"service": "my-service",
"version": "1.0.0",
"environment": "production",
"debug": false,
"uptime": "running"
},
"database": {
"status": "connected",
"driver": "mysql",
"connection_name": "mysql"
},
"cache": {
"status": "working",
"driver": "redis"
},
"system": {
"php_version": "8.2.12",
"laravel_version": "11.0.0",
"memory_usage": {
"current": "8.5 MB",
"peak": "12.1 MB",
"limit": "128M"
},
"disk_space": {
"free": "45.2 GB",
"total": "100.0 GB",
"used_percentage": 54.8
}
},
"response_time": "45.23ms"
}
Storage Health Check
GET /health/storage
Returns storage backend health information (only available if storage checks are enabled).
Liveness Probe
GET /health/liveness
Kubernetes liveness probe endpoint. Returns simple alive status.
Response:
{
"status": "alive",
"timestamp": "2025-01-27T10:30:45.123Z"
}
Readiness Probe
GET /health/readiness
Kubernetes readiness probe endpoint. Checks if the application is ready to serve traffic.
Response:
{
"status": "ready",
"timestamp": "2025-01-27T10:30:45.123Z",
"checks": {
"database": "ready",
"storage": "ready"
}
}
Custom Health Checks
You can create custom health checks by implementing the HealthCheckInterface:
<?php
namespace App\HealthChecks;
use Federicozardi\LaravelHealthCheck\Contracts\HealthCheckInterface;
class CustomServiceCheck implements HealthCheckInterface
{
public function check(): array
{
// Your custom health check logic
return [
'status' => 'healthy',
'message' => 'Custom service is working',
'connection_ok' => true,
];
}
public function getName(): string
{
return 'custom_service';
}
public function isCritical(): bool
{
return true; // This check is critical for the application
}
}
Then register it in your configuration:
// config/health-check.php
'custom_checks' => [
'custom_service' => \App\HealthChecks\CustomServiceCheck::class,
],
Logging Configuration
The package includes comprehensive logging for health check errors and events. Logging integrates seamlessly with Laravel's logging system.
Basic Logging Configuration
// config/health-check.php
'logging' => [
'enabled' => true,
'channel' => 'default', // Laravel logging channel to use
'level' => 'error', // Minimum log level (debug, info, warning, error, critical)
'context' => [
'include_environment' => true,
'include_request_id' => false,
'include_user_id' => false,
],
],
Custom Logging Channel
You can use a dedicated logging channel for health checks:
// config/logging.php
'channels' => [
'health_check' => [
'driver' => 'single',
'path' => storage_path('logs/health-check.log'),
'level' => 'error',
],
],
// config/health-check.php
'logging' => [
'enabled' => true,
'channel' => 'health_check',
'level' => 'error',
],
Log Output Examples
Database Connection Error:
{
"message": "Health check 'database' failed",
"context": {
"check": "database",
"error": "SQLSTATE[HY000] [2002] Connection refused",
"error_class": "PDOException",
"driver": "mysql",
"connection_name": "mysql",
"host": "localhost",
"environment": "production",
"timestamp": "2025-01-27T10:30:45.123Z"
},
"level": "error",
"level_name": "ERROR",
"channel": "health_check",
"datetime": "2025-01-27T10:30:45.123456+00:00"
}
Cache System Warning:
{
"message": "Health check 'cache' warning: Cache system degraded - read/write test failed",
"context": {
"check": "cache",
"message": "Cache system degraded - read/write test failed",
"driver": "redis",
"retrieved_value": null,
"environment": "production",
"timestamp": "2025-01-27T10:30:45.123Z"
},
"level": "warning",
"level_name": "WARNING",
"channel": "health_check",
"datetime": "2025-01-27T10:30:45.123456+00:00"
}
Advanced Logging with Slack Integration
// config/logging.php
'channels' => [
'health_check' => [
'driver' => 'stack',
'channels' => ['single', 'slack'],
],
'slack' => [
'driver' => 'slack',
'url' => env('LOG_SLACK_WEBHOOK_URL'),
'username' => 'Health Check Bot',
'emoji' => ':warning:',
'level' => 'error',
],
],
Storage Backend Monitoring
To monitor custom storage backends, implement the StorageBackendInterface:
<?php
namespace App\Storage;
use Federicozardi\LaravelHealthCheck\Contracts\StorageBackendInterface;
class CustomStorageBackend implements StorageBackendInterface
{
public function healthCheck(): array
{
// Your storage health check logic
return [
'available' => true,
'connection_ok' => true,
'storage_type' => 'custom',
];
}
public function getStorageInfo(): array
{
return [
'driver' => 'custom',
'available' => true,
'version' => '1.0.0',
];
}
public function getName(): string
{
return 'custom_storage';
}
}
Kubernetes Integration
Liveness Probe
livenessProbe:
httpGet:
path: /health/liveness
port: 80
initialDelaySeconds: 30
periodSeconds: 10
Readiness Probe
readinessProbe:
httpGet:
path: /health/readiness
port: 80
initialDelaySeconds: 5
periodSeconds: 5
Testing
Run the test suite:
composer test
Run tests with coverage:
composer test-coverage
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This package is open-sourced software licensed under the MIT license.
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
Support
If you discover any security related issues, please email security@example.com instead of using the issue tracker.