Projects in this organization. Pass a slug or a name to the other tools, or * for every project.
Docs
Set up the account, the client, and the rule.
Confirm the email, create a project, and put the key in the browser or in TRACEHAWK_DSN. Slack and Jira wait until a rule crosses a count you set.
Account
Register an organization and confirm the email. The workspace opens after that confirmation. Base and Business include a 3-day trial. Submitting the form does not charge a card. After the trial, the workspace stays closed until an owner or admin subscribes from Billing.
Project and key
An owner or admin opens Projects and creates one. The platform is PHP, Python, Go, or JavaScript. It chooses the install snippet on the project page and the shape of the test error. The snippet, tracehawk/sdk, the Python client, and the Go module can still post to the same project key.
Allowed origins are one per line, for the browser snippet. Leave the list empty while you try it locally. An empty list accepts every browser origin. PHP, Python, and Go send no Origin header, so the list does not apply to them.
The project key is shown once, as TRACEHAWK_DSN and, for a JavaScript project, as the script tag. Reloading the page hides it. Rotate from the project page when you need a new one. The old key can keep working for 24 hours, 3 days, or 7 days, or stop immediately. You can also set an expiry date, or expire the key now.
Browser
Paste the script where the page loads. async keeps a dead host from blocking the page. The key is public, so set the production origin before you ship. The JavaScript page covers captureException, breadcrumbs, and the release.
<script async
src="https://tracehawk.net/api/<public-key>/snippet.js"
crossorigin="anonymous"
onload="TraceHawk.setRelease('shop@1.4.2')"></script>
The snippet reports uncaught errors and unhandled promise rejections. A try/catch you already handled stays quiet until you call TraceHawk.captureException.
PHP, Laravel, Symfony
The package is tracehawk/sdk 1.2.3 and needs PHP 8.2 or newer. Point Composer at the TraceHawk repository, then set the DSN to the project key.
composer config repositories.tracehawk composer https://tracehawk.net/sdk composer require tracehawk/sdk:1.2.3
TRACEHAWK_DSN=https://tracehawk.net/api/<key>
Laravel is one call in bootstrap/app.php. The provider reads the DSN, reports each HTTP request, and the call below sends uncaught exceptions. Laravel install.
use TraceHawk\Sdk\Laravel\Integration;
->withExceptions(function (Exceptions $exceptions) {
Integration::handles($exceptions);
})
Symfony is one line in config/bundles.php. Flex will not discover the package from Packagist. Symfony install.
TraceHawk\Sdk\Symfony\TraceHawkBundle::class => ['all' => true],
A plain PHP app calls the client itself: TraceHawk::init, an exception handler that calls TraceHawk::capture, and TraceHawk::trackRequest at the end of the HTTP request. Plain PHP has the full script. If TraceHawk is unreachable, the report gives up in under half a second and the request continues.
Laravel and Symfony send application logs through a Monolog channel. The handler is TraceHawk\Sdk\LogHandler. Existing logger calls stay as they are. A line does not open an issue, and it counts as a request.
Python, Django, Flask
The package is tracehawk 1.0.0 and needs Python 3.9 or newer. Install the wheel from TraceHawk, then set the DSN to the project key.
pip install https://tracehawk.net/sdk/python/tracehawk-1.0.0-py3-none-any.whl
TRACEHAWK_DSN=https://tracehawk.net/api/<key>
Django is one middleware line. Flask is one call. Both read the DSN, report each HTTP request, and send uncaught exceptions. A 404 is not reported. Python install.
"tracehawk.django.TraceHawkMiddleware", from tracehawk.flask import install install(app)
A plain Python app calls the client itself: TraceHawk.init, an exception hook that calls TraceHawk.capture, and TraceHawk.track_request at the end of the HTTP request. If TraceHawk is unreachable, the report gives up in under half a second and the request continues.
Application logs use tracehawk.logging.LogHandler on the logger you already have. Existing logger.info calls stay as they are. A line does not open an issue, and it counts as a request. TraceHawk.log sends one line when you are not using the logging module.
Go
The module is tracehawk.net/sdk/go v1.0.0 and needs Go 1.21 or newer. The import path is the module path, then set the DSN to the project key.
go get tracehawk.net/sdk/go@v1.0.0
TRACEHAWK_DSN=https://tracehawk.net/api/<key>
tracehawk.Handler wraps net/http. It reports a panic and the request, then re-panics. A 404 written by the next handler is not reported. chi uses the same wrapper. Go install.
tracehawk.Init(os.Getenv("TRACEHAWK_DSN"))
http.ListenAndServe(":8080", tracehawk.Handler(mux))
A service that does not use that wrapper calls tracehawk.Capture and tracehawk.TrackRequest itself. If TraceHawk is unreachable, the report gives up in under half a second and the request continues.
Paths to ignore
A health check or a third-party script you cannot change should not become an issue, and it should not be billed. On the project page, Ignored URLs is one pattern per line. * is a wildcard. A matching page, request, thrown file, or script URL is dropped. Spans to a matching URL are left out of the trace.
*googletagmanager.com* https://js.stripe.com/* /webhooks/*
PHP and Python can skip paths before they are sent. Laravel reads config/tracex.php or TRACEHAWK_IGNORE=/ping,/health*. Symfony, Django, and Flask read TRACEHAWK_IGNORE the same way. Go skips a path when you pass it to tracehawk.Ignore. A match is not sent, including an exception raised while handling that path.
Release and user
Set a release so the issue can show the first and last version that sent the error. In the browser, call TraceHawk.setRelease from the script onload, because an inline script after an async tag can run too early. In PHP, call TraceHawk::setRelease after the client has booted. In Python, call TraceHawk.set_release after init. In Go, call tracehawk.SetRelease after Init. AppServiceProvider::boot is a straightforward place in Laravel.
TraceHawk::setRelease('shop@1.4.2');
TraceHawk::setUser((string) $request->user()?->getAuthIdentifier());
TraceHawk::addBreadcrumb('checkout', 'Card step opened');
Laravel copies APP_ENV into the environment. Symfony uses APP_ENV, or prod when that value is missing. You can still call setEnvironment when you want a different label.
Send a test error
On the project page, Send a test error. It shows up on Issues before any production traffic. Open it and check the stack, the release, and the request. Counts, first seen, and last seen belong to the issue. The stack and breadcrumbs belong to the event you have open.
Members
An owner or admin invites from Members, as a member or an admin. The invite is for one email address. That person signs in, or creates an account, and joins this organization. The owner can later change a role. A member creates their own MCP keys and sees the issues. Creating a project, rotating the ingest key, and editing automation stay with an owner or admin.
Slack and Jira
Automation is saved per project. An owner or admin connects it. Slack is an incoming webhook. The URL is stored encrypted. Jira Cloud needs the site URL, such as https://your-team.atlassian.net, the Atlassian account email, and an API token. Leave the token field blank later if you only want to keep the saved one. There is no marketplace app.
A team is where the Jira task lands: a name, the Jira project key, the issue type (Bug is the default), and optional labels. Slack does not need a team.
A rule has a name, one project or all projects, the environments it watches, and a window of 15 minutes, 1 hour, 6 hours, or 24 hours. Slack posts at its own count. The Jira task waits for a heavier count and uses the team you picked. "Repeat if it regresses" is on by default: resolving the issue and seeing the same stack come back can open another task. The Jira page is the longer version.
Business creates the Slack message and the Jira task when a rule is crossed. On Base the connection can be saved, and a burst does not send it.
MCP
Open MCP in the workspace and create a key. It is separate from the project key in the snippet and in TRACEHAWK_DSN. A new project does not print an MCP key.
- Name the key after the machine, such as Laptop. The token is shown once. Copy it before you reload. You can keep 20 of your own keys on one project.
- Paste the header block into the client. Cursor reads mcp.json. On the request that created the key, the workspace fills the token into a block named after the project slug.
- The agent can search issues, error events, logs, and telemetry, open one record, and change status, assignee, or priority. Those lists start on the project the key was created on. Pass project as * for the whole organization. search_events finds text in a stack or breadcrumb. list_logs and list_telemetry search the other two streams. kind n_plus_one returns the heaviest N+1 issues.
A member sees the keys they created. An owner or admin sees every key and can delete any of them. One key works on every project in the organization. Arguments for each tool are on the MCP page.
Paste this into the client's MCP config. Cursor reads it from mcp.json. The key stays in the Authorization header.
{
"mcpServers": {
"tracehawk": {
"url": "https://tracehawk.net/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}
Some clients accept a URL and cannot send a header. Put the key in the path. Use the header form when the client can send headers, so the key stays out of the URL.
https://tracehawk.net/mcp/YOUR_KEY
People in this organization. Role is owner, admin, or member. Access is Admin or Developer. assign_issue accepts a name or an email from this list.
Grouped issues on the key's project. search matches the title, short id, culprit, or exception type. Filter by status, project, or kind n_plus_one.
Events on one issue, newest first. Copy an event_id into get_issue to open an older event.
One issue and one event: exception, stack, repeated query, request URL, and breadcrumbs.
Find an error by text in the exception, message, URL, transaction, stack, or breadcrumbs. The reply has short_id and event_id for get_issue.
Log lines, newest first. search matches the message and the context. Session, user, and email are exact.
One log line, including its context.
Client events and crashes. Every search word must match. type is event or crash.
One telemetry record: message, error, and payload.
Mark an issue unresolved, resolved, or ignored.
Assign a member by name or email. An empty assignee clears it.
Set low, medium, or high. Omit the priority, or pass an empty string, to clear it.
Questions
When can I see the project key again?
Once, on the project page, right after you create the project or rotate the key. Reloading hides it. Rotate if you did not copy it.
Do I need a separate project for the browser, PHP, Python, and Go?
No. The snippet, tracehawk/sdk, the Python client, and the Go module can post to the same project key. The platform picks the install snippet and the test error.
Which plan sends Slack and Jira?
Business. Base can store the webhook and the Jira token, and a burst does not send them.
Who can create an MCP key?
Anyone in the organization, including a member. An owner or admin sees every key. A member sees only the keys they created.