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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

• Federico Zardi
• All Contributors

Support

If you discover any security related issues, please email security@example.com instead of using the issue tracker.