Error Tracking 2.12

Evolve sites report errors to Sentry through the official sentry/sentry-laravel package. All client sites of the agency report into one shared Sentry project, so every event needs to say which site, which environment and which deploy it came from. Since 2.12 Evolve adds that context itself.

Default behaviour

When sentry/sentry-laravel is installed, every event gets:

Field	Value	Source
tag site	host of APP_URL, e.g. www.example-client.ch	left out when APP_URL has no host
tag environment_type	live, staging or development	EVOLVE_ENV_TYPE, or inferred from APP_ENV (Environments)
release	evolve@<version>+<release directory>, e.g. evolve@2.12.0+20260926143012	only when the project sets no release of its own

Nothing to configure. Without sentry/sentry-laravel the integration does nothing; the package is suggested, not required.

The release format

• <version> is the installed racerfish/evolve version, without the leading v.
• <release directory> is the releases/<YmdHis> directory the deploy created, read from the path the app runs from (the current symlink resolved). Locally and in CI there is no release directory and the release is just evolve@2.12.0.
• Characters Sentry does not accept in release names (slashes, whitespace, as in branch versions like dev-feat/x) become -.

Sentry reads package@version+build as a semantic version. Releases therefore sort and group by Evolve version, queries like release.version:>=2.12.0 work, and the build part still keeps two deploys of the same version apart, so "first seen in" and "regressed in" stay meaningful per deploy.

Precedence

Evolve only fills what is still empty. The order inside the Sentry client:

1. The project's Sentry options are applied (release, environment from config/sentry.php).
2. Scope tags the project sets are applied.
3. The Evolve event processor adds site, environment_type and the release where they are missing.
4. The project's own before_send runs last and can change or remove everything.

So a project that sets SENTRY_RELEASE, or its own site or environment_type tag, keeps its value.

Configuration

Evolve adds no configuration of its own. The variables are those of sentry/sentry-laravel:

Env variable	Default	Effect
SENTRY_LARAVEL_DSN	unset	The project DSN. Without a DSN nothing is sent.
SENTRY_DSN	unset	Legacy name, read when SENTRY_LARAVEL_DSN is not set.
SENTRY_RELEASE	unset	A release of your own. Wins over the Evolve release.
SENTRY_ENVIRONMENT	APP_ENV	Sentry's own environment field. Independent of the environment_type tag.

Install and configure it per project:

composer require sentry/sentry-laravel

SENTRY_LARAVEL_DSN=https://<key>@<org>.ingest.sentry.io/<project>

Finding a site's events

In the shared project, filter the issue and event search by tag:

site:www.example-client.ch
environment_type:live
site:www.example-client.ch environment_type:live release.version:>=2.12.0
release:evolve@2.12.0+20260926143012

Checking the DSN before go-live

evolve:env:verify has a Sentry DSN line for live environments since 2.12. It reads the server .env and never prints the DSN itself:

Check	Result	Details	When
Sentry DSN	✓ pass	set	SENTRY_LARAVEL_DSN or SENTRY_DSN holds a value
Sentry DSN	! warn	not set, add SENTRY_LARAVEL_DSN so errors on live are reported	both are missing, empty or null
Sentry DSN	! warn	sentry/sentry-laravel is not installed, errors on live are not reported	the package is not installed in the project

It is a warning, not a failure, because Sentry is optional for the package. Staging environments are not checked.

php artisan evolve:env:verify live
php artisan evolve:env:verify --all

Limits

• Traces. The dynamic sampling context of transactions (the sentry-release baggage value) is computed from the client options, not from events, so traces keep the project's release, or none. Errors and transactions themselves carry the Evolve release.
• APP_URL must be right. The site tag is only as good as APP_URL. A live site still on http://localhost reports site:localhost; the canonical host health check catches that too.

Verifying on a server

# 1. DSN present in the live .env
php artisan evolve:env:verify live

# 2. Send a test event from the server
php artisan evolve:ssh live
cd current && php84 artisan sentry:test

The test event shows up in Sentry with the tags site and environment_type and a release evolve@<version>+<release directory> that matches readlink current on the server.