Health Check Results Laravel Package

Technical Evaluation

Architecture Fit

• Lightweight & Modular: The package is designed as a thin abstraction layer for generating Oh Dear-compatible health check JSON, making it ideal for Laravel applications requiring observability without heavy dependencies.
• Event-Driven Compatibility: Aligns well with Laravel’s event system (e.g., booted, scheduled:run) for periodic health checks.
• Extensibility: Supports custom checks (e.g., database connectivity, queue health) via CheckResult objects, enabling granular monitoring.

Integration Feasibility

• Laravel-Native: Leverages PHP 8.4+ features (e.g., named arguments, typed properties) and follows Laravel’s DI/Service Container patterns.
• Oh Dear Dependency: Requires Oh Dear’s monitoring setup (webhook endpoint) but abstracts the JSON payload generation.
• Low Coupling: No database or external service dependencies; purely logic-driven.

Technical Risk

• Version Alignment: PHP 8.4+ required; may need minor adjustments for older Laravel versions (e.g., 9.x).
• Meta Data Schema: Dynamic meta field in CheckResult could lead to runtime type inconsistencies if not validated.
• Testing Gaps: Limited test coverage for edge cases (e.g., malformed timestamps, nested meta data).

Key Questions

1. Monitoring Scope: Will this replace existing health checks (e.g., Laravel’s Artisan::call('down')) or augment them?
2. Data Flow: How will health check results be transmitted to Oh Dear (e.g., HTTP client, queue job)?
3. Alerting Strategy: Are there existing alerting systems (e.g., Slack, PagerDuty) that need integration?
4. Performance Impact: Will checks run synchronously during requests or asynchronously (e.g., via Laravel Queues)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Seamlessly integrates with:
  • Console Commands (e.g., php artisan health:check).
  • Middleware (e.g., /health endpoint).
  • Tasks (e.g., scheduler:run).
• Oh Dear Compatibility: Generates the exact JSON schema Oh Dear expects, reducing parsing errors.
• Testing Tools: Works with Pest/PHPUnit via CheckResults assertions.

Migration Path

1. Phase 1: Pilot Checks
   • Implement 2–3 critical checks (e.g., disk space, DB connectivity) in a staging environment.
   • Validate Oh Dear’s webhook ingestion and alerting.
2. Phase 2: Full Rollout
   • Replace legacy health check scripts with CheckResults.
   • Deprecate redundant monitoring tools (e.g., custom cron jobs).
3. Phase 3: Optimization
   • Add caching for frequent checks (e.g., Redis).
   • Implement rate limiting to avoid Oh Dear API throttling.

Compatibility

• PHP 8.4+: Requires Laravel 10.x+ or PHP 8.4-compatible Laravel 9.x.
• Oh Dear API: No breaking changes expected; adheres to Oh Dear’s docs.
• Laravel Services: Works alongside existing services (e.g., DB, Cache) without conflicts.

Sequencing

1. Setup Oh Dear:
   • Configure webhook endpoint in Oh Dear dashboard.
   • Ensure Laravel can reach Oh Dear’s API (no firewall blocks).
2. Package Installation:

   composer require ohdearapp/health-check-results
   

3. Implement Checks:
   • Create a service class (e.g., app/Services/HealthCheckService) to aggregate CheckResult objects.
   • Example:

     use OhDearApp\HealthCheckResults\CheckResults;
     use OhDearApp\HealthCheckResults\CheckResult;
     
     public function runChecks(): CheckResults {
         $results = new CheckResults(now());
         $results->addCheckResult(new CheckResult(
             name: 'DatabaseConnection',
             label: 'Database Connectivity',
             status: DB::connection()->getPdo() ? CheckResult::STATUS_OK : CheckResult::STATUS_FAILED,
             notificationMessage: 'Database is unreachable!',
         ));
         return $results;
     }
     

4. Expose Endpoint:
   • Add a route (e.g., GET /oh-dear-health) to return JSON:

     Route::get('/oh-dear-health', function () {
         return response()->json((new HealthCheckService())->runChecks());
     });
     

5. Automate:
   • Schedule checks via Laravel’s scheduler or cron:

     $schedule->command('health:check')->hourly();
     

Operational Impact

Maintenance

• Low Overhead: Minimal maintenance; updates align with Oh Dear’s API changes.
• Dependency Management: Single Composer package with no transitive conflicts.
• Logging: Add Laravel logs for failed checks (e.g., Log::error($checkResult->notificationMessage)).

Support

• Debugging: Use dd($results) to inspect payloads during development.
• Oh Dear Dashboard: Centralized view of all checks; reduces support ticket volume.
• Documentation: Update internal runbooks with:
  • How to add new checks.
  • Oh Dear webhook troubleshooting (e.g., 4xx errors).

Scaling

• Performance:
  • Synchronous: Lightweight for small apps; avoid during peak traffic.
  • Asynchronous: Use Laravel Queues for heavy checks (e.g., database integrity scans).
• Concurrency: Thread-safe for multi-server setups (e.g., Laravel Forge).
• Cost: Free tier of Oh Dear supports unlimited checks; paid plans for advanced features.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 15 mins: Install and run basic checks.
  • 1 hour: Customize checks (e.g., add queue health).
  • 1 day: Integrate with Oh Dear alerts and dashboards.
• Training:
  • Record a Loom video demonstrating check creation.
  • Document common check examples (e.g., Redis, storage).
• Rollback Plan:
  • Maintain legacy health check scripts until Oh Dear integration is stable.
  • Use feature flags to toggle health check endpoints.