Myaku Health Check Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devexploris/myaku-health-check
   

   Add to config/bundles.php:

   return [
       Devexploris\MyakuHealthCheck\MyakuHealthCheckBundle::class => ['all' => true],
   ];
   

2. Route Registration: Add to config/routes.yaml:

   myaku_health_check:
       resource: Devexploris\MyakuHealthCheck\Controller\HealthCheckController
       type: attribute
   

3. First Use Case: Access GET /health to verify the endpoint works. The response will include disk space, memory (Linux only), database, and cache statuses.

Where to Look First

• Configuration: config/packages/myaku_health_check.yaml (create if missing).
• Security: Set APP_MYAKU_TOKEN in .env (generate with openssl rand -hex 24).
• Thresholds: Define threshold.space and threshold.memory if needed (e.g., threshold: { space: 80 }).

First Integration

For a Laravel developer migrating from Symfony, replace Symfony’s health_check bundle with this package. The /health endpoint replaces Laravel’s php artisan down or custom health checks. Use it in:

• Monitoring tools (e.g., Prometheus, Datadog).
• CI/CD pipelines to validate deployment health.
• Load balancers for failover logic.

Implementation Patterns

Workflows

1. Basic Health Check:

   // In a Laravel controller or service
   $response = Http::get('http://localhost/health');
   $health = json_decode($response->body(), true);
   if ($health['database']['connected'] === false) {
       throw new \RuntimeException('Database unavailable');
   }
   

2. Threshold-Based Alerts: Configure thresholds in myaku_health_check.yaml:

   myaku_health_check:
       threshold:
           space: 90
           memory: 95
   

   • threshold_targeted: true in the response indicates a breach.

3. IP Whitelisting: Restrict access to specific IPs:

   security:
       whitelist:
           - "127.0.0.1"
           - "192.168.1.100"
   

4. Token Authentication: Include the token in requests:

   curl -H "x-myaku-token: YOUR_TOKEN_HERE" http://localhost/health
   

Integration Tips

• Laravel-Specific: Use the endpoint in Laravel’s AppServiceProvider for bootstrapping checks:

  public function boot()
  {
      $health = Http::get('http://localhost/health')->json();
      if ($health['database']['connected'] === false) {
          Log::error('Database unavailable during boot');
      }
  }
  

• Monitoring Integration: Parse the JSON response in tools like:

  • Prometheus: Scrape /health and extract metrics (e.g., space_used_percent).
  • Grafana: Visualize thresholds and latency.

• Custom Checks: Extend the bundle by creating a custom checker (see Extension Points).

• Environment-Specific Config: Use Laravel’s .env for dynamic thresholds:

  threshold:
      space: "%env(int:MYAKU_SPACE_THRESHOLD, 80)%"
  

Gotchas and Tips

Pitfalls

1. Memory Check on Non-Linux: The memory check fails silently on macOS/Windows (returns connected: false). Document this in your monitoring alerts.

2. Database/Cache Auto-Detection: If doctrine.dbal.default_connection or cache.app are missing, the checks are skipped. Verify these services are registered in Symfony’s container.

3. Token Security:

   • Store the token in .env (e.g., APP_MYAKU_TOKEN).
   • Rotate tokens periodically (e.g., via openssl rand -hex 24).

4. Threshold Logic:

   • Thresholds are percentage-based (e.g., space: 80 = 80% usage).
   • threshold_targeted: true triggers a 503 response.

5. IP Whitelist Strictness:

   • If whitelist is empty, all IPs are allowed.
   • If non-empty, only listed IPs pass.

Debugging

1. 503 Responses: Check the JSON response for threshold_targeted: true or error fields in database/cache.

2. 403 Forbidden:

   • Verify the x-myaku-token header matches .env.
   • Confirm the client IP is in the whitelist (if configured).

3. Missing Checks:

   • Ensure doctrine.dbal.default_connection and cache.app are available in Symfony’s container.
   • For Laravel, manually bind these services if using custom configurations.

Tips

1. Custom Checkers: Extend the bundle by implementing Devexploris\MyakuHealthCheck\Checker\CheckerInterface:

   namespace App\HealthChecks;
   
   use Devexploris\MyakuHealthCheck\Checker\CheckerInterface;
   
   class CustomChecker implements CheckerInterface
   {
       public function check(): array
       {
           return [
               'status' => 'ok',
               'data' => ['custom_metric' => 42],
           ];
       }
   }
   

   Register it in services.yaml:

   services:
       App\HealthChecks\CustomChecker:
           tags: ['myaku_health_check.checker']
   

2. Latency Metrics: Use the latency field in database/cache for performance monitoring.

3. Testing: Mock the /health endpoint in Laravel tests:

   $response = Http::fake([
       'http://localhost/health' => Http::response(['space' => ['free' => '100%']], 200),
   ]);
   

4. Laravel-Symfony Bridge: If using Laravel, wrap the Symfony bundle in a Laravel service provider to handle route registration and configuration:

   namespace App\Providers;
   
   use Illuminate\Support\ServiceProvider;
   use Devexploris\MyakuHealthCheck\MyakuHealthCheckBundle;
   
   class MyakuHealthCheckProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->register(MyakuHealthCheckBundle::class, ['all' => true]);
       }
   }
   

5. Log Critical Failures: In a Laravel event listener or service, log 503 responses:

   if ($health['database']['connected'] === false) {
       Log::critical('Database connection failed', ['error' => $health['database']['error']]);
   }