README

Unravel shows you what actually happened inside your Laravel application: the incoming HTTP request, the SQL queries it ran, the jobs it queued, the logs and exceptions along the way.

The idea is simple: when someone says "it broke," you open one trace and see the whole chain of events — instead of piecing it together by hand from logs, Sentry, and guesswork.

The SDK hooks into standard Laravel events and captures:

• incoming HTTP requests
• SQL queries and bindings
• cache hits / misses / writes
• logs and exceptions
• outgoing HTTP client requests
• queued jobs, artisan commands, scheduled tasks
• mail, notifications, broadcasts
• Laravel Reverb / WebSocket events

Installation

composer require unravel/laravel

Create a project at app.unravel.run, open Connect, and copy the ingest key it gives you:

UNRAVEL_API_KEY=unrv_…

That's it. Laravel auto-discovers the package and capture starts immediately — there is no service provider to register and no code to instrument by hand. Send any request through your app and the dashboard goes live within seconds.

Treat the key like any other credential: keep it out of version control, and revoke and re-mint it in the dashboard if it leaks.

Verify the install

To confirm your key and URL are right and events reach the cloud, run:

php artisan unravel:test

It prints the resolved config (capture on/off, cloud URL, masked API key) and sends a single synthetic log event straight to <UNRAVEL_CLOUD_URL>/events, then reports the result: success (HTTP 200), 401 (key rejected — check UNRAVEL_API_KEY), 404 (the URL is missing its version segment, e.g. https://api.unravel.run/v1), 429 (rate limited), or a network error (host unreachable, DNS/TLS, wrong URL). It works even with UNRAVEL_ENABLED=false, so you can use it to find out why capture is off.

On success the event appears in the Logs section of your dashboard within a few seconds — an info entry reading Unravel SDK connectivity test.

How it works

Every request, job, command, or WebSocket connection gets a trace_id. Every event that happens inside it inherits the same id, so Unravel can stitch them back into one story — even when it spans several processes (an HTTP request, the jobs it dispatched, the messages they broadcast).

The SDK is deliberately thin. It doesn't group SQL, classify errors, or do any heavy lifting inside your app — it just collects events into memory and ships them to the Unravel backend in one batch at the end of each request, job, or command, after the response has already gone out to the user. All the analysis happens server-side, never on your app's hot path.

Why it's safe

The SDK's first rule is: never hurt your application.

• It never throws its own errors into your code.
• Network problems don't break a request, job, or command — if the backend is slow or down, the SDK gives up quietly rather than retrying.
• Sensitive values (passwords, tokens, auth headers, cookies) are scrubbed, and large user-supplied data is truncated, before anything leaves your server.
• Nothing is written to your database. The only thing it ever writes to disk is its own diagnostics log (storage/logs/unravel.log), and only when a flush fails — successful flushes are logged only if you opt in with UNRAVEL_DEBUG_TRANSPORT=true.

To turn the SDK off entirely — for example in a specific environment — use the kill switch rather than removing the package:

UNRAVEL_ENABLED=false

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13
• ext-curl, ext-json

Server compatibility

The SDK is built for the standard request/job lifecycle and is verified on:

• PHP-FPM / mod_php — the primary target.
• Long-running CLI workers — queue:work, queue:listen, Horizon, schedule:run/schedule:work (detected automatically, blocking transport).
• Laravel Reverb — WebSocket events captured via a dedicated async transport. This needs react/http, which is not a hard dependency (it would conflict with modern Laravel's psr/http-message), so install it explicitly in Reverb apps: composer require react/http. Without it, WebSocket events are skipped and a warning is logged — the rest of the SDK is unaffected.

Laravel Octane is not supported in v0.1. Octane keeps the application resident between requests, and the SDK relies on container singletons that hold per-request trace state — this state can bleed across requests, and a queue-payload carrier is registered in a way that does not survive worker reuse. Run your app under PHP-FPM until Octane support lands. This also applies to all Octane runtimes (Swoole / Open Swoole, RoadRunner, FrankenPHP worker mode); FrankenPHP's classic non-worker mode behaves like FPM and is fine.

Documentation

Full documentation lives at unravel.run/docs — configuration, what's captured, security, and limits.

Contributing

This repository is a read-only split of a private monorepo — pull requests are welcome and get merged via the monorepo with your authorship preserved. See CONTRIBUTING.md.

License

MIT