Sentry

Errors and performance of the site in Sentry.

kitloom/sentry · admins: kitloom/sentry-filament, kitloom/sentry-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

Sentry Settings

Sends the site's errors to Sentry: what broke, on which page, for which kind of visitor, and what was changed on the site just before. Works with sentry.io, a self-hosted Sentry and GlitchTip. The admin page is the Sentry section (kitloom/sentry-filament or kitloom/sentry-nova).

Connecting the site

1. In Sentry, create a project (platform: Laravel) and copy its DSN — Project Settings → Client Keys (DSN). It looks like https://[email protected]/456.
2. In the admin, open Sentry → Settings, paste the DSN and save.
3. Press Send test event (in Nova: tick Send a test event on save and save). The event shows up in Sentry → Issues within a minute. If the page says Sentry did not take it, the DSN is wrong or the server cannot reach Sentry.

Sentry starts with the next request. Under Octane a new DSN works after php artisan octane:reload.

Field	What it means
DSN	Where the events go. Empty — Sentry is off.
Environment	The name events are filed under (production, staging…). Empty — the application's environment.
Traced requests, %	The share of requests whose timing goes to Sentry's Performance: database queries, rendering. 0 — errors only. On a busy site 5–20 % is plenty; every traced request counts against the Sentry quota.
Report JavaScript errors from the site's pages	The theme's pages load Sentry's browser SDK and report errors of the page's scripts to the same project. Off by default.

When SENTRY_LARAVEL_DSN is set in the server's environment, the environment rules: the connection fields only show its values and are not saved. The browser switch still works.

Errors in visitors' browsers

Turned on, every page of the theme loads Sentry's browser SDK from Sentry's CDN (with its integrity hash) and reports JavaScript errors with the same DSN and environment, tagged with the page's template (kitloom.template). Visitors with an ad blocker may block it — Sentry sees fewer browser errors than there are.

The theme must have @siteHead in its layout (every kitloom theme has); a theme of your own adds @siteHead, @siteBodyOpen and @siteFooter to its root layout. Nothing about the visitor is put into the page — it is cached the same for everyone. With a Content Security Policy, allow https://browser.sentry-cdn.com for scripts and the Sentry host for connections; a nonce set with Vite::useCspNonce() goes on the scripts.

When the database is down

The settings live in the database, and a DSN read from it would be missing exactly when the database fails. So each server keeps a copy of them in storage/app/kitloom-sentry.json, read before the database is asked anything: the error "database is down" still reaches Sentry. The status on the settings page says whether this server's copy is up to date. The copy is rewritten on every save and checked against the settings once a minute, which is how the other servers of a site learn of a change. A server that has never reached its database since it was deployed has no copy — give such setups SENTRY_LARAVEL_DSN.

What the site adds to Sentry's events

What	Switch (kitloom-sentry.*)
Exceptions are reported by the module — no Integration::handles($exceptions) in bootstrap/app.php (with it, turn this off, or every exception arrives twice)	report_exceptions
Pages named by the template hierarchy instead of one fallback route: single-book, page, front-page, home, category, tag, taxonomy-genre, author, date, archive-book, search, 404	transaction_names
Tag kitloom.page and context kitloom_page: kind, post type or taxonomy, object id, page number	page_context
The signed-in user's id, nothing else; with sentry.send_default_pii the SDK sends the user itself	user_id
Content saved, published, trashed, restored or deleted before the error — book 12 saved: ids, types and statuses, no titles	content_breadcrumbs

For developers

• Settings: sentry_dsn, sentry_environment, sentry_traces_percent, sentry_browser (declared by SentryOptions, written through SettingWriter; a DSN the SDK cannot parse is refused).
• SentryConfig::apply() puts the local copy into Sentry's config while the application boots; TestEvent::send() sends a message with its own client and returns the transport's answer (success, invalid, unknown when Sentry could not be reached) — the SDK gives an event id even to an event Sentry refused.
• BrowserScripts is a PageScriptsProvider of kitloom/site; the SDK's url and hash are in kitloom-sentry.browser, a newer SDK is a config change.
• php artisan vendor:publish --tag=kitloom-sentry-config for kitloom-sentry.php: the copy's path (KITLOOM_SENTRY_LOCAL_COPY; under unit tests there is no copy unless a test names one) and check interval, the switches above, the admin sections (filament.register, nova.register). Everything else is sentry-laravel's own config/sentry.php.
• Tests, from the application that installs the package: php vendor/bin/phpunit --testsuite Sentry.