---
url: /site/error-tracking.md
---
# Error Tracking 

Evolve sites report errors to [Sentry](https://sentry.io) 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](/getting-started/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:

```bash
composer require sentry/sentry-laravel
```

```ini [.env]
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.

```bash
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

```bash
# 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.