JavaScript
JavaScript error tracking.
One script tag reports uncaught errors and unhandled promise rejections. Caught errors stay quiet until you call captureException.
What it does
The snippet is served from your project key. It listens for window.error and unhandledrejection, parses the stack, and posts JSON to https://tracehawk.net/api/<key>/store. Recent clicks on links, buttons, and inputs are kept as breadcrumbs, along with the path when the page loaded. A failed post is ignored, and async keeps a dead host from blocking the page.
The key is in the page source. Set allowed origins on the project before production. An empty list accepts every browser origin. PHP is not limited by that list.
Install
<script async
src="https://tracehawk.net/api/<public-key>/snippet.js"
crossorigin="anonymous"
onload="TraceHawk.setRelease('shop@1.4.2')"></script>
async means a following inline script can run before TraceHawk exists. onload runs after the snippet has installed the API. You can also wait for the load event:
window.addEventListener('load', function () {
if (!window.TraceHawk) return;
TraceHawk.setRelease('shop@1.4.2');
TraceHawk.setUser('u_84213');
TraceHawk.setTag('page', 'checkout');
});
An error you already caught
try {
checkout();
} catch (error) {
TraceHawk.captureException(error);
}
captureException accepts an optional second argument with tags, user, and contexts. It does not replace the automatic listener. Use it when your code caught the error and the browser will not emit window.error.
Supported features
- Uncaught errors and unhandled promise rejections, with up to 25 stack frames.
- Click breadcrumbs and a navigation breadcrumb. The snippet keeps the latest ones and sends 30.
- setRelease, setUser, setTag, and addBreadcrumb.
- A page transaction with LCP, INP, and CLS, sent when the tab hides or after eight seconds, plus the largest resources on the page.
- The same grouping and Jira rule as a PHP exception.
Troubleshooting
- The browser console shows a 403 with "Origin is not allowed for this project." Add the exact origin, scheme and host, with no trailing slash. https://shop.example and https://shop.example/ are not the same entry.
- An empty allowed-origin list accepts every origin. That is useful locally and too open for production.
- A cross-origin script without CORS headers arrives as "Script error" with an empty stack. That is the browser, not a dropped event.
- A Content-Security-Policy that does not allow https://tracehawk.net will block the snippet.
- TraceHawk is not defined means the config script ran before the async snippet finished. Move the call to onload or the window load event.
- A caught exception is not sent unless you call captureException.
Questions
Does the snippet catch errors inside a try/catch?
No. A handled error does not fire window.error. Call TraceHawk.captureException(error) in the catch block.
Is the project key secret?
No. It is in the page. Restrict it with allowed origins, and rotate it from the project page if it leaks further than you want. The full key is shown once.
Will the script block rendering if TraceHawk is down?
The install uses async, so the browser does not wait for the host before continuing the page.
Can I set the release after the snippet loads?
Yes. Use the script onload attribute or the window load event. An inline script immediately after an async tag can run too early.