Laravel
Laravel exception monitoring.
tracehawk/sdk reports uncaught Laravel exceptions and every HTTP request. Repeated stacks become one issue. A release and a trace stay on the event.
What it does
The service provider reads TRACEHAWK_DSN, or TRACEX_DSN if that name is already set, and initializes the client. It sets the environment from APP_ENV. On the way out of a real HTTP request it sends the method and path, plus spans collected during the request. Artisan is not reported as an HTTP request.
Uncaught exceptions are sent only after you register the handler below. An exception you already caught does not reach that handler, so call TraceHawk::capture($e) yourself. If TraceHawk is unreachable, the call gives up in under half a second and the request continues.
Install
The package requires PHP 8.2 or newer. The documented Laravel install is the exception hook in bootstrap/app.php.
composer config repositories.tracehawk composer https://tracehawk.net/sdk composer require tracehawk/sdk:1.1.0
TRACEHAWK_DSN=https://tracehawk.net/api/<key>
# bootstrap/app.php
use TraceHawk\Sdk\Laravel\Integration;
->withExceptions(function (Exceptions $exceptions) {
Integration::handles($exceptions);
})
Release, user, and a handled exception
Call these after the package has booted. AppServiceProvider::boot is a straightforward place for the release. Capture is for an exception your own code already handled.
use TraceHawk\Sdk\TraceHawk;
TraceHawk::setRelease('shop@1.4.2');
TraceHawk::setUser((string) $request->user()?->getAuthIdentifier());
TraceHawk::addBreadcrumb('checkout', 'Card step opened');
try {
$order->charge();
} catch (Throwable $e) {
TraceHawk::capture($e);
throw $e;
}
Supported features
- Uncaught exceptions, including the previous exception when one is attached.
- One report per HTTP request, with the method and path.
- Spans for SQL, outgoing HTTP client calls, cache hits and misses, and queue jobs handled during the request.
- A queue worker running in the console reports the job itself, rather than pretending it was an HTTP request.
- Release, environment, user id, and up to 30 breadcrumbs.
- The same grouping, issue page, and Jira rule as a browser event.
A repeated query pattern or a slow request can become its own issue from those spans. Session replay is not part of the product.
Troubleshooting
- Nothing arrives: TRACEHAWK_DSN must be the project URL, https://tracehawk.net/api/<key>, and the key must belong to an open workspace.
- Requests arrive and exceptions do not: Integration::handles is missing from bootstrap/app.php.
- A try/catch you already handled stays silent until you call TraceHawk::capture.
- Allowed origins do not apply. PHP sends no Origin header.
- php artisan does not create an HTTP event. That is intentional.
Questions
Does the Laravel client report handled exceptions?
No. Integration::handles only sees exceptions Laravel is reporting. Call TraceHawk::capture($e) inside a catch block when you still want that exception stored.
Will a failed report break the request?
No. The PHP client gives up in under half a second and swallows its own failure so the original request or exception is unchanged.
Which environment is stored?
The service provider copies APP_ENV. You can still call TraceHawk::setEnvironment if you want a different value.
Do I need a separate project for the browser?
No. The browser snippet and the PHP package can post to the same project key. Grouping does not split them by client.