README

This package provides a simple way to monitor your application by sending exception data to a webhook endpoint. It includes traits and utilities to automatically send exception information from jobs, notifications, and other parts of your application. Compatible with PHP 8.1+ and Laravel 10+.

Installation

You can install the package via composer (compatible with PHP 8.1+ and Laravel 10+):

composer require nazirul-amin/sentinel-actor

You can publish the config file with:

php artisan vendor:publish --tag="sentinel-actor-config"

This is the contents of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Monitoring Client Configuration
    |--------------------------------------------------------------------------
    |
    | Here you can configure the monitoring client settings.
    |
    */

    'webhook' => [
        'url' => env('SENTINEL_WEBHOOK_URL'),
        'endpoint' => env('SENTINEL_EXCEPTION_URL', '/application/exceptions'),
        'status_endpoint' => env('SENTINEL_STATUS_URL', '/application/status'),
        'application_id' => env('SENTINEL_APPLICATION_ID', 'app-id'),
        'application_version' => env('SENTINEL_APPLICATION_VERSION', '1.0.0'),
        'secret' => env('SENTINEL_WEBHOOK_SECRET'),
    ],

    'enabled' => env('SENTINEL_ENABLED', true),

    'levels' => [
        'info',
        'success',
        'warning',
        'error',
        'critical'
    ],
];

Configuration

Add the following environment variables to your .env file:

SENTINEL_WEBHOOK_URL=https://your-monitoring-service.com/webhook
SENTINEL_EXCEPTION_URL=/application/exceptions
SENTINEL_STATUS_URL=/application/status
SENTINEL_APPLICATION_ID=your-app-name
SENTINEL_APPLICATION_VERSION=1.0.0
SENTINEL_WEBHOOK_SECRET=your-hmac-secret
SENTINEL_ENABLED=true

HMAC Signature Verification

This package supports HMAC signature verification for enhanced security. When you configure a secret in your .env file, all outgoing webhook requests will be signed with HMAC-SHA256.

The receiving service can verify the authenticity of the request by comparing the signature in the Sentinel-Signature header with a locally computed signature using the same secret.

Usage

Monitoring Exceptions in Jobs

To automatically send exception data from your jobs, simply use the MonitorsExceptions trait:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use NazirulAmin\SentinelActor\Traits\MonitorsExceptions;
use Throwable;

class YourJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels, MonitorsExceptions;

    // Your job properties and methods

    public function handle()
    {
        // Your job logic here
    }

    // Optional: Add context data to be sent with exception
    protected function getMonitoringContextData(): array
    {
        return [
            'job_specific_data' => $this->someProperty,
        ];
    }
}

Monitoring Exceptions in Notifications

Similarly, you can monitor exceptions in notifications:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;
use NazirulAmin\SentinelActor\Traits\MonitorsExceptions;

class YourNotification extends Notification implements ShouldQueue
{
    use Queueable, MonitorsExceptions;

    // Your notification properties and methods

    public function via($notifiable)
    {
        return ['mail'];
    }

    public function toMail($notifiable)
    {
        // Your notification logic here
    }

    // Optional: Add context data to be sent with exception
    protected function getMonitoringContextData(): array
    {
        return [
            'notification_specific_data' => $this->someProperty,
        ];
    }
}

Application Health Status Monitoring

To send application health status updates (active/inactive), use the UpdatesApplicationStatus trait:

<?php

namespace App\Services;

use NazirulAmin\SentinelActor\Traits\UpdatesApplicationStatus;

class HealthCheckService
{
    use UpdatesApplicationStatus;

    public function checkHealth()
    {
        try {
            // Perform health checks
            $isHealthy = $this->performHealthChecks();

            // Send health status
            $this->updateHealthStatus($isHealthy, $isHealthy ? 'Application is healthy' : 'Application is unhealthy', [
                'checked_at' => now()->toISOString(),
                'environment' => app()->environment(),
            ]);
        } catch (Exception $e) {
            // Send unhealthy status on error
            $this->updateHealthStatus(false, 'Health check failed: ' . $e->getMessage());
        }
    }

    private function performHealthChecks(): bool
    {
        // Implement your health checks here
        // Return true if healthy, false if unhealthy
        return true;
    }

    // Optional: Add context data to be sent with status updates
    protected function getStatusContextData(): array
    {
        return [
            'service_specific_data' => $this->someProperty,
        ];
    }
}

Scheduled Health Checks

The package includes a built-in health check command that can be scheduled to run periodically:

// In your App\Console\Kernel class
protected function schedule(Schedule $schedule)
{
    $schedule->command('sentinel:health-check')
             ->everyMinute()
             ->withoutOverlapping();
}

This command performs basic health checks and sends the status to your monitoring service. You can customize the health checks by extending the command.

Manual Exception Monitoring

You can also manually send exception data using the facade:

use NazirulAmin\SentinelActor\Facades\SentinelActor;
use Throwable;

try {
    // Some code that might throw an exception
} catch (Throwable $exception) {
    SentinelActor::sendException($exception, [
        'additional_context' => 'some_value',
    ]);
}

Sending Custom Events

You can also send custom events to your monitoring service:

use NazirulAmin\SentinelActor\Facades\SentinelActor;

SentinelActor::send('/application/events', [
    'application_id' => 'your-app-name',
    'application_version' => '1.0.0', // Automatically added by the package
    'environment' => 'production', // Automatically added by the package
    'event_type' => 'user_registered',
    'level' => 'info',
    'message' => 'A new user registered',
    'context' => [
        'user_id' => 123,
    ],
    'timestamp' => time(),
]);

Webhook Payload Structure

All webhooks sent by this package include the following data:

Exception Webhooks

• application_id: The application identifier from config
• application_version: The application version from config
• environment: The current Laravel environment (local, production, staging, etc.)
• type: Set to 'exception'
• message: The exception message
• file: The file where the exception occurred
• line: The line number where the exception occurred
• timestamp: Unix timestamp when the exception occurred
• code: The exception code
• trace: The full exception trace
• context: Additional context information

Health Status Webhooks

• application_id: The application identifier from config
• application_version: The application version from config
• environment: The current Laravel environment (local, production, staging, etc.)
• type: Set to 'health_status'
• status: Either 'active' or 'inactive'
• healthy: Boolean value indicating health status (true/false)
• message: Optional message describing the health status
• timestamp: Unix timestamp when the health status was sent
• context: Additional context information

Status Update Webhooks (Legacy)

• application_id: The application identifier from config
• application_version: The application version from config
• environment: The current Laravel environment (local, production, staging, etc.)
• type: Set to 'status_update'
• status: The status being reported (e.g., 'running', 'stopped', 'maintenance')
• message: Optional message describing the status
• timestamp: Unix timestamp when the status update was sent
• context: Additional context information

All requests are signed with HMAC-SHA256 for security.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• nazirulamin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.