README

Ranetrace is an all-in-one tool for Error Tracking, Website Analytics, and Website Monitoring for Laravel applications.

Alerts you about errors and provides the context you need to fix them
Privacy-first, fully server-side website analytics — no cookies and no client-side scripts; visitors are identified only by salted, one-way hashes (never raw identifiers, never across sites)
Monitors uptime, performance, SSL certificates, domain and DNS status, Lighthouse scores, and broken links

Check out the Ranetrace website for more information.

Installation

Install the package via Composer:

composer require ranetrace/ranetrace-laravel

Add your Ranetrace key to .env:

RANETRACE_KEY=your-key-here

Optionally publish the config file:

php artisan vendor:publish --tag="ranetrace-laravel-config"

Schedule the work command

Captured items (errors, events, logs, page visits, JS errors) are buffered locally and sent to Ranetrace in batches by the ranetrace:work artisan command. Add it to your scheduler:

// In your scheduler (routes/console.php)
Schedule::command('ranetrace:work')
    ->everyMinute()
    ->withoutOverlapping()
    ->runInBackground();

Don't skip this step. Without it, buffered telemetry never reaches Ranetrace. Run php artisan ranetrace:status at any time to verify health and see whether buffers are draining.

Usage

Error Tracking

Wire Ranetrace into Laravel's exception handling in bootstrap/app.php:

use Illuminate\Foundation\Configuration\Exceptions;
use Ranetrace\Laravel\Facades\Ranetrace;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withExceptions(function (Exceptions $exceptions) {
        Ranetrace::handles($exceptions);
    })
    ->create();

That's it — every unhandled exception is now reported to your Ranetrace dashboard (alongside Laravel's normal logging). You can also capture exceptions in-flow:

use Ranetrace\Laravel\Facades\Ranetrace;

try {
    // ...
} catch (Throwable $e) {
    Ranetrace::report($e);
    throw $e;
}

Test your setup with:

php artisan ranetrace:test-errors

JavaScript Error Tracking

Enable it in your .env:

RANETRACE_JAVASCRIPT_ERRORS_ENABLED=true

Add the Blade directive to your layout:

<body>
    @yield('content')

    @ranetraceErrorTracking
</body>

The directive injects a small script that captures window.onerror, unhandled promise rejections, and (optionally) console.error calls. It also collects breadcrumbs for clicks, form submissions, and XHR/fetch activity to give you context around each error.

You can also capture errors manually:

window.Ranetrace.captureError(error, { payment_amount: amount });

Event Tracking

Track custom events with a privacy-first approach — no IP addresses are stored, user agents are hashed, and session IDs rotate daily.

use Ranetrace\Laravel\Facades\Ranetrace;

Ranetrace::trackEvent('button_clicked', [
    'button_id' => 'header-cta',
    'page' => 'homepage'
]);

E-commerce helpers are available via the RanetraceEvents facade:

use Ranetrace\Laravel\Facades\RanetraceEvents;

RanetraceEvents::sale(
    orderId: 'ORDER-456',
    totalAmount: 89.97,
    products: [['id' => 'PROD-123', 'name' => 'Widget', 'price' => 29.99, 'quantity' => 3]],
    currency: 'USD'
);

Test your setup with:

php artisan ranetrace:test-events

Centralized Logging

Enable it in your .env:

RANETRACE_LOGGING_ENABLED=true

The package auto-registers a ranetrace log channel — no config/logging.php edit is required. Add it to your existing log stack so application logs are routed to both your normal destination AND Ranetrace:

// config/logging.php — example stacked channel
'channels' => [
    'production' => [
        'driver' => 'stack',
        'channels' => array_merge(explode(',', env('LOG_STACK', 'single')), ['ranetrace']),
        'ignore_exceptions' => false,
    ],
],

Then point Laravel at it:

LOG_CHANNEL=production

By default the package captures notice and above. Tune via RANETRACE_LOGGING_LEVEL.

Test your setup with:

php artisan ranetrace:test-logging

Website Analytics

Enable it in your .env:

RANETRACE_WEBSITE_ANALYTICS_ENABLED=true

The TrackPageVisit middleware is automatically added to the web middleware group. It applies extensive bot and crawler filtering before sending visits to your Ranetrace dashboard. No code changes needed.

See the Ranetrace website for dashboard setup and configuration details.

Health Check

The package gives you two ways to see what it's doing locally: a CLI command and an in-app dashboard. Both read the same underlying diagnostics, so they can never disagree.

Status command

At any time, from the terminal:

php artisan ranetrace:status

Reports overall health, configured features, buffer sizes, pause states (if the API has rate-limited you), and recent failed jobs — both as formatted output and via --json for monitoring integrations. When the dashboard is enabled, it also prints a one-line link to it.

Diagnostics dashboard

An in-app health page at /ranetrace, in the spirit of Laravel Horizon and Pulse. It shows whether your installation is correctly wired up and data is flowing: a configuration snapshot, misconfiguration checks (missing API key, volatile cache driver, stalled worker, near-capacity buffers, and more), pipeline buffers, pauses, failed jobs, a tail of the internal log, and the routes/middleware the package actually registered. It links out to the hosted Ranetrace dashboard for the captured data itself.

It is read-only, makes no outbound calls, and degrades gracefully — a failing cache or database renders a degraded panel rather than throwing into your app.

Access is local-only by default. Exactly like Horizon, Pulse, and Telescope, the dashboard is not reachable outside the local environment until you explicitly grant access. Define the viewRanetrace gate in app/Providers/AppServiceProvider.php:

use Illuminate\Support\Facades\Gate;

Gate::define('viewRanetrace', function ($user) {
    return in_array($user->email, [
        'admin@example.com',
    ]);
});

The dashboard is configurable in config/ranetrace.php, all overridable via .env:

RANETRACE_DASHBOARD_ENABLED=true            # set false to remove the routes entirely
RANETRACE_DASHBOARD_PATH=ranetrace          # the URL path
RANETRACE_DASHBOARD_REFRESH=10              # auto-refresh interval in seconds (0 = off)
RANETRACE_DASHBOARD_DOMAIN=                 # optional: serve on a dedicated domain
RANETRACE_DASHBOARD_HOSTED_URL=https://ranetrace.com  # "View captured data" link target

The page auto-refreshes its panels every RANETRACE_DASHBOARD_REFRESH seconds without a full reload. It is registered independently of the master RANETRACE_ENABLED switch, so if capture is disabled or misconfigured you can still open the dashboard to see why.

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

License

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

ranetrace / ranetrace-laravel

Maintainers

Package info

Statistics

Security

README

Installation

Schedule the work command

Usage

Error Tracking

JavaScript Error Tracking

Event Tracking

Centralized Logging

Website Analytics

Health Check

Status command

Diagnostics dashboard

Testing

Changelog

Contributing

Security Vulnerabilities

Credits

License