0015. Observability with Sentry and spatie/laravel-health checks
Generated from api/docs/adr/0015-observability-sentry-and-health-checks.md
- Status: Accepted (retroactive)
- Date: 2021-10-12
Context and Problem Statement
Section titled “Context and Problem Statement”A headless API running in containers across environments (and later many tenants) needs error reporting and a liveness signal for orchestrators.
Considered Options
Section titled “Considered Options”Evidenced: Sentry (kept), Laravel Telescope (tried and removed), spatie/laravel-health.
Decision Outcome
Section titled “Decision Outcome”sentry/sentry-laravelfrom the first commit; exception reporting was wired throughapp/Exceptions/Handler.phpandconfig/sentry.phpin71cc950b(2021-10-12). DSN and environment come from env vars. SDK upgraded to ^4.2 with Laravel 9.- Laravel Telescope was added (
a797a937, 2022-03-15) and removed five weeks later (54fb87bd, 2022-04-21). Reason not recorded. Inferred: unsuitable for a stateless production image. spatie/laravel-healthwith aHealthCheckProviderand an API route, used by the DockerHEALTHCHECK(b49b22bb, 2024-10-04).- Multi-domain mode got a default domain configuration “to resolve sentry issues” (
b6f90be3).
Consequences
Section titled “Consequences”- Good: production errors are captured centrally; containers report health.
- Bad: no tracing/metrics stack beyond Sentry; Telescope-style local introspection is absent.
- Bad: in multi-domain mode Sentry events need the domain as context to be actionable.
Evidence
Section titled “Evidence”05ceebba2021-03-03 “initical commit” —sentry/sentry-laravel ^2.3.71cc950b2021-10-12 “Sentry update” —api/config/sentry.php,api/app/Exceptions/Handler.php.a797a9372022-03-15 “Add telescope”;54fb87bd2022-04-21 “remove telescope”.b49b22bb2024-10-04 —api/app/Providers/HealthCheckProvider.php,api/config/health.php.b6f90be32024-12-17 “defautl setup for multidomain to resolve sentry issues”.