PHP
PHP exception monitoring.
tracehawk/sdk is a small PHP 8.2 client. You point it at a project, capture the exception, and it keeps the stack, the previous exception, and a trace id.
What it does
There is no automatic hook for a plain PHP app. TraceHawk::init reads the DSN. TraceHawk::capture sends one exception. TraceHawk::trackRequest sends the HTTP request that just finished. Laravel and Symfony call those for you. A plain script calls them itself.
The report includes the exception class and message, up to 40 frames, up to five previous exceptions, the release, the environment, a user id if you set one, and up to 30 breadcrumbs. Vendor frames and the SDK file are marked outside the application so grouping can prefer your code.
Install
composer config repositories.tracehawk composer https://tracehawk.net/sdk composer require tracehawk/sdk:1.1.0
TRACEHAWK_DSN=https://tracehawk.net/api/<key>
use TraceHawk\Sdk\TraceHawk;
TraceHawk::init(getenv('TRACEHAWK_DSN') ?: '');
TraceHawk::setEnvironment('production');
TraceHawk::setRelease('app@1.0.0');
set_exception_handler(function (Throwable $e): void {
TraceHawk::capture($e);
});
register_shutdown_function(function (): void {
if (PHP_SAPI === 'cli') {
return;
}
TraceHawk::trackRequest();
});
Put that where the application boots, before your own code runs. Skip trackRequest in CLI scripts unless you want the command reported as a request. Laravel already avoids that.
A handled exception
try {
$payment->charge();
} catch (Throwable $e) {
TraceHawk::addBreadcrumb('payment', 'Charge failed');
TraceHawk::capture($e);
throw $e;
}
Supported features
- Exception class, message, and stack, with lines around the crashing frame when the file can be read.
- The previous exception chain, up to five deep.
- Release, environment, user id, and breadcrumbs.
- A trace id on the event, and any spans you add with TraceHawk::addSpan.
- An HTTP transaction when you call trackRequest.
- The same issue grouping as Laravel, Symfony, and the browser snippet.
Plain PHP does not collect SQL or cache spans on its own. Those collectors ship with the Laravel provider.
Troubleshooting
- An empty DSN disables the client. init returns without an endpoint, and later calls do nothing.
- The documented DSN is https://tracehawk.net/api/<key>. A value that already ends in /store is also accepted.
- Calling capture twice for the same throw only sends the first. The client ignores a nested report.
- Allowed origins are a browser control. PHP is not filtered by that list.
- If the host is down, the HTTP call stops in under half a second. Your script keeps going.
Questions
Do I have to use Laravel or Symfony?
No. The same package works from plain PHP if you call init, capture, and trackRequest yourself. Laravel and Symfony are shortcuts for those calls.
What PHP version does the SDK require?
PHP 8.2 or newer, as declared by tracehawk/sdk 1.1.0.
Will secrets in local variables be stored?
Variable names that look like a password, secret, token, credential, or API key are stored as [Filtered]. Do not put secrets in the exception message, tags, or user id.