unravel.
Open dashboard

Docs · Getting started

Installation

Unravel installs as a Composer package and hooks the framework's own events. There are no service providers to register and no code to instrument by hand.

Requirements

  • PHP 8.2 or newer
  • Laravel 11 or newer
  • An ingest key from your project's Settings → API keys in the dashboard

Server compatibility

Unravel is built for the standard request, job, and command lifecycle. It is verified on:

  • PHP-FPM and mod_php - the primary target.
  • Long-running CLI workers - queue:work, queue:listen, Horizon, and the scheduler (schedule:run, schedule:work). These are detected automatically.
  • Laravel Reverb - websocket events are captured through a dedicated async transport. This needs one extra package; see the Laravel Reverb section below.

Laravel Octane is not supported yet. Octane keeps the application resident between requests, and the current capture layer relies on per-request state that is reset at the end of each request - under Octane that state can carry over into the next request. This applies to every Octane runtime (Swoole, Open Swoole, RoadRunner, and FrankenPHP in worker mode). Run your app under PHP-FPM until Octane support ships. FrankenPHP's classic, non-worker mode behaves like PHP-FPM and works fine.

Install the package

composer require unravel/laravel

Laravel auto-discovers the package, so there is nothing to register manually.

Laravel Reverb

If you run Laravel Reverb, Unravel captures websocket activity (connections, channels, subscriptions, frames) through a dedicated async transport built on react/http. That package is not a hard dependency of the SDK: react/http requires psr/http-message ^1, which clashes with the ^2 that current Laravel and Guzzle use, so making it mandatory would block the SDK from installing in most apps. Install it yourself in Reverb apps:

composer require react/http

Without it the websocket transport stays off - those events are skipped and a single warning is logged, while everything else keeps working normally.

Add your key

Create a project in the dashboard, open Connect, and copy the ingest key it mints for you. Add it to your environment:

UNRAVEL_API_KEY=unrv_…

You do not need to set a cloud URL: the SDK defaults to production. Keep the key secret and out of version control, exactly like any other credential. If a key leaks, revoke it in the dashboard and generate a new one.

Verify

Run the built-in diagnostic to confirm your key and URL are correct and that events actually reach the cloud:

php artisan unravel:test

It prints the resolved config (capture on/off, cloud URL, masked key) and sends a single test event straight to the ingest endpoint, then tells you exactly what happened: accepted, key rejected, a URL missing its version segment, rate limited, or a network error. It works even with capture disabled, so you can use it to find out why nothing is being collected.

On success the event lands in the Logs section within a few seconds, an info entry with the message Unravel SDK connectivity test. (Because it has no parent request or job, it also shows up in Traces as a one-event trace.)

Otherwise, just send any request through your app: within a few seconds the dashboard flips from the waiting state to live data. The onboarding screen polls for your first event and advances automatically once it arrives.

Environments

Run the same key across prod, staging, and local, or mint a key per environment. Environments are free under a project: you are never charged per environment. See Configuration to label them.