PHPackages allanzico/laravel-helios - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. allanzico/laravel-helios ActiveLibrary[Logging & Monitoring](/categories/logging) allanzico/laravel-helios ======================== A lightweight, self-hosted monitoring tool for Laravel applications with real-time tracking of logs, jobs, queries, and performance. v1.0.1(8mo ago)121Apache-2.0TypeScriptPHP ^8.2 Since Oct 11Pushed 8mo agoCompare [ Source](https://github.com/allanzico/laravel-helios)[ Packagist](https://packagist.org/packages/allanzico/laravel-helios)[ RSS](/packages/allanzico-laravel-helios/feed)WikiDiscussions main Synced today READMEChangelogDependencies (4)Versions (3)Used By (0) Laravel Helios ============== [](#laravel-helios) A lightweight, self-hosted monitoring tool for Laravel applications. Helios provides real-time monitoring of: - Slow and failed requests - Application Logs - Queued Jobs - Scheduled Tasks - Slow Database Queries - Health Checks - Error Tracking Features -------- [](#features) - **Real-time Monitoring**: Track your Laravel application's performance in real-time - **Modern UI**: Beautiful React-based dashboard with TanStack Router and Query - **Easy Installation**: Simple Composer installation with automatic service provider registration - **Lightweight**: Minimal overhead on your application - **Self-hosted**: All data stays in your database - **Error Tracking**: Automatic error grouping and tracking with detailed stack traces - **Queue Actions**: Retry or forget failed queue jobs from the dashboard - **Scheduled Commands**: Run known scheduled tasks manually when enabled Requirements ------------ [](#requirements) - PHP 8.2 or higher - Laravel 11.0 or higher (Laravel 11, 12, and 13 supported) - MySQL/PostgreSQL database Installation ------------ [](#installation) ### 1. Install via Composer [](#1-install-via-composer) ``` composer require allanzico/laravel-helios ``` The service provider will be automatically registered via Laravel's package auto-discovery. ### 2. Run Migrations [](#2-run-migrations) ``` php artisan migrate ``` This will create the following tables: - `helios_jobs` - Track queued jobs - `helios_queries` - Database query logs - `helios_requests` - HTTP request tracking - `helios_scheduled_tasks` - Scheduled task execution logs - `helios_task_definitions` - Scheduled task definitions - `helios_health_check_settings` - Health check configuration - `helios_errors` - Error tracking and grouping ### 3. Open Helios [](#3-open-helios) **That's it!** Frontend assets are automatically inlined (similar to Laravel Horizon), so no asset publishing is required. Helios will try to discover scheduled tasks from Laravel's schedule automatically. If your app only exposes scheduled tasks through a console kernel, you can still sync them manually: ``` php artisan helios:sync-tasks ``` > **Note:** If you're upgrading from an earlier version, clear your view cache: `php artisan view:clear` Usage ----- [](#usage) Once installed, access the Helios dashboard at: ``` http://your-app.com/helios ``` For local development: ``` http://localhost:8000/helios ``` ### Dashboard Features [](#dashboard-features) - **Overview**: Problems-first health summary, failed jobs, errors, slow requests, and slow queries - **Operations**: Health checks, queue status/actions, and scheduler monitoring/manual runs - **Performance**: Request and query performance samples - **Events**: Application logs and grouped errors Local Playground ---------------- [](#local-playground) This repo includes a real Laravel playground app in `playground/` that installs Helios through a local Composer path repository. ``` bash scripts/playground.sh ``` Then open: ``` http://127.0.0.1:8001 http://127.0.0.1:8001/helios ``` To generate sample requests, queries, logs, errors, and a failed queued job: ``` bash scripts/playground-demo.sh ``` Testing ------- [](#testing) Run the package test suite with: ``` composer install composer test ``` Run the playground smoke tests with: ``` cd playground php artisan test ``` Configuration ------------- [](#configuration) ### Publishing Resources (Optional) [](#publishing-resources-optional) You can publish configuration and other resources if needed for customization: ``` # Publish config file php artisan vendor:publish --tag=helios-config # Publish views (for customization) php artisan vendor:publish --tag=helios-views # Publish migrations (if you want to modify them) php artisan vendor:publish --tag=helios-migrations ``` **Note:** Asset publishing is not required. All CSS and JavaScript are automatically inlined in the HTML, similar to how Laravel Horizon works. ### Configuration File [](#configuration-file) Optionally publish and customize the configuration file: ``` php artisan vendor:publish --tag=helios-config ``` This creates `config/helios.php`: ``` return [ 'enabled' => env('HELIOS_ENABLED', true), 'path' => env('HELIOS_PATH', 'helios'), 'middleware' => [ 'web', \Allanzico\LaravelHelios\Http\Middleware\Authorize::class, ], 'allowed_environments' => ['local', 'testing'], 'gate' => 'viewHelios', 'strict_authorization' => true, 'log_path' => storage_path('logs'), 'watchers' => [ 'requests' => [ 'enabled' => env('HELIOS_REQUESTS_ENABLED', true), 'slow_ms' => (float) env('HELIOS_SLOW_REQUEST_MS', 1000), 'sample_rate' => (float) env('HELIOS_REQUEST_SAMPLE_RATE', 0.05), ], 'queries' => [ 'enabled' => env('HELIOS_QUERIES_ENABLED', true), 'slow_ms' => (float) env('HELIOS_SLOW_QUERY_MS', 100), 'sample_rate' => (float) env('HELIOS_QUERY_SAMPLE_RATE', 0.0), ], 'schedule' => [ 'enabled' => env('HELIOS_SCHEDULE_ENABLED', true), 'allow_manual_runs' => env('HELIOS_ALLOW_MANUAL_SCHEDULE_RUNS', false), 'manual_allowlist' => [], ], ], 'actions' => [ 'run_scheduled_tasks' => env('HELIOS_ALLOW_MANUAL_SCHEDULE_RUNS', false), 'retry_jobs' => env('HELIOS_ALLOW_JOB_RETRY', false), 'forget_jobs' => env('HELIOS_ALLOW_JOB_FORGET', false), 'clear_logs' => env('HELIOS_ALLOW_LOG_CLEAR', false), 'purge_data' => env('HELIOS_ALLOW_PURGE_DATA', false), ], 'security' => [ 'store_query_bindings' => env('HELIOS_STORE_QUERY_BINDINGS', false), 'store_request_body' => env('HELIOS_STORE_REQUEST_BODY', false), 'store_request_headers' => env('HELIOS_STORE_REQUEST_HEADERS', false), 'show_health_meta' => env('HELIOS_SHOW_HEALTH_META', app()->environment(['local', 'testing'])), ], 'health' => [ 'scheduler' => [ 'lookback_minutes' => (int) env('HELIOS_SCHEDULER_HEALTH_LOOKBACK_MINUTES', 1440), 'grace_minutes' => (int) env('HELIOS_SCHEDULER_HEALTH_GRACE_MINUTES', 5), ], 'redis' => [ 'enabled' => env('HELIOS_HEALTH_REDIS_ENABLED'), ], 'environment' => [ 'expected' => env('HELIOS_HEALTH_EXPECTED_ENV'), ], 'storage' => [ 'paths' => [ storage_path('framework/cache'), storage_path('logs'), ], ], ], 'retention_days' => (int) env('HELIOS_RETENTION_DAYS', 7), 'error_tracking' => [ 'enabled' => env('HELIOS_ERROR_TRACKING_ENABLED', true), 'group_by_line' => env('HELIOS_ERROR_GROUP_BY_LINE', false), ], ]; ``` ### Production Access [](#production-access) In production, define a `viewHelios` gate in your application: ``` use Illuminate\Support\Facades\Gate; Gate::define('viewHelios', fn ($user = null) => $user?->email === 'you@example.com'); ``` Optional action-specific gates are also supported: ``` Gate::define('runHeliosTask', fn ($user = null) => $user?->isAdmin()); Gate::define('retryHeliosJob', fn ($user = null) => $user?->isAdmin()); Gate::define('forgetHeliosJob', fn ($user = null) => $user?->isAdmin()); Gate::define('clearHeliosLog', fn ($user = null) => $user?->isAdmin()); Gate::define('purgeHeliosData', fn ($user = null) => $user?->isAdmin()); ``` ### Environment Variables [](#environment-variables) Add to your `.env` file: ``` # Enable/disable all of Helios HELIOS_ENABLED=true # Move the dashboard path HELIOS_PATH=helios # Tune collection HELIOS_SLOW_REQUEST_MS=1000 HELIOS_SLOW_QUERY_MS=100 HELIOS_REQUEST_SAMPLE_RATE=0.05 HELIOS_QUERY_SAMPLE_RATE=0 # Enable/disable error tracking HELIOS_ERROR_TRACKING_ENABLED=true # Manual actions HELIOS_ALLOW_MANUAL_SCHEDULE_RUNS=false HELIOS_SCHEDULE_MANUAL_ALLOWLIST=reports:daily,cache:warm HELIOS_ALLOW_JOB_RETRY=false HELIOS_ALLOW_JOB_FORGET=false HELIOS_ALLOW_LOG_CLEAR=false HELIOS_ALLOW_PURGE_DATA=false # Sensitive data capture HELIOS_STORE_QUERY_BINDINGS=false HELIOS_STORE_REQUEST_BODY=false HELIOS_STORE_REQUEST_HEADERS=false HELIOS_SHOW_HEALTH_META=false # Scheduler health HELIOS_SCHEDULER_HEALTH_LOOKBACK_MINUTES=1440 HELIOS_SCHEDULER_HEALTH_GRACE_MINUTES=5 HELIOS_HEALTH_REDIS_ENABLED= HELIOS_HEALTH_EXPECTED_ENV= ``` ### Queue Actions [](#queue-actions) Helios uses Laravel's configured failed-job provider for retry and forget actions. Actions are supported when the failed-job provider stores UUIDs that match Helios job IDs, such as `database-uuids`, `file`, and `dynamodb`. Legacy numeric failed-job IDs from the `database` failed driver are shown as unsupported because Helios cannot safely map them back to the UUIDs emitted by Laravel queue events. Error Tracking -------------- [](#error-tracking) Automatic error tracking is registered by the package service provider. You do not need to replace your application's exception handler. Health Checks ------------- [](#health-checks) Helios includes operational health checks for application boot, database, cache, Redis, disk space, storage writability, queue status, scheduler freshness, and environment configuration. Redis is skipped unless Redis is used by cache, queue, or session configuration, or `HELIOS_HEALTH_REDIS_ENABLED=true`. The scheduler freshness check compares discovered scheduled tasks against their cron expressions. If a task was due within the configured lookback window but Helios has not recorded a scheduler-triggered run within the grace period, the check fails. Purging Old Data ---------------- [](#purging-old-data) You can purge old monitoring data directly from the dashboard when `HELIOS_ALLOW_PURGE_DATA=true`, or programmatically: ``` use Allanzico\LaravelHelios\Models\HeliosRequest; use Allanzico\LaravelHelios\Models\HeliosQuery; use Allanzico\LaravelHelios\Models\HeliosJob; // Delete old data HeliosRequest::where('created_at', '