Installation - Laravel

Before you start, create a project in the DockRay panel. Its settings hold the project token - the public identifier that goes into the ingest URL - and the API keys tab is where you generate a private key. The key is shown once, when it is generated: DockRay stores only its hash. If you do not have a project yet, start with Getting Started.

Requirements

• Laravel 10 or newer,
• PHP 8.2 or newer,
• Composer 2.

Installing the package

composer require dockcodes/dock-ray-laravel
php artisan vendor:publish --tag=ray-config

The service provider is discovered automatically - there is nothing to register by hand. Publishing the configuration creates config/ray.php; without it the package still runs on its defaults.

Credentials

RAY_TOKEN=project-token
RAY_PRIVATE_KEY=project-private-key
RAY_TRACES_SAMPLE_RATE=0.2

Without RAY_TOKEN and RAY_PRIVATE_KEY the package stays inert: no requests, no errors. That is why you can wire it once and never wrap it in a condition - the local environment simply gets no credentials.

Wiring exception reporting

Laravel 11 and 12, in bootstrap/app.php:

use Dock\Ray\Laravel\Ray;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->reportable(fn (Throwable $e) => Ray::report($e));
})

Laravel 10, in app/Exceptions/Handler.php:

public function register(): void
{
    $this->reportable(fn (Throwable $e) => Ray::report($e));
}

Ray::report() never throws and never rethrows: a monitoring outage must not break the error handling it was called from. It also returns void, so it does not cut off the framework's own logging.

Request timing

Timing needs the middleware added to the groups you want measured - usually web and api:

->withMiddleware(function (Illuminate\Foundation\Configuration\Middleware $middleware) {
    $middleware->appendToGroup('web', \Dock\Ray\Laravel\Http\Middleware\TrackTransaction::class);
})

Nothing is measured while ray.traces_sample_rate is 0.

The first test

Easiest from Tinker - the call travels the same path as reporting from the application:

php artisan tinker --execute="\Dock\Ray\Laravel\Ray::message('DockRay control message');"