fotospiel-app/docs/ops/monitoring-glitchtip.md

title, sidebar_label

title	sidebar_label
GlitchTip (Error Monitoring)	GlitchTip

GlitchTip 5.2 is our Sentry-compatible error and performance monitoring stack. It lives at https://logsder.fotospiel.app and accepts the standard Sentry SDKs (Laravel + React). This page explains how to wire the DSNs, roll it out in Docker/Dokploy, and how to sanity-check events. Keep PII out of breadcrumbs and context; log only what is needed to debug.

1) Environment variables

Set these in .env (never commit) and ensure they are passed through Docker (docker-compose.dokploy.yml already forwards them):

SENTRY_LARAVEL_DSN=https://<key>@logsder.fotospiel.app/<project-id>
SENTRY_ENVIRONMENT=production
SENTRY_TRACES_SAMPLE_RATE=0.05   # adjust per env
SENTRY_PROFILES_SAMPLE_RATE=0.02 # optional profiling
SENTRY_RELEASE=$(git rev-parse --short HEAD)

VITE_SENTRY_DSN=https://<key>@logsder.fotospiel.app/<project-id>
VITE_SENTRY_ENV=production
VITE_SENTRY_RELEASE=$(git rev-parse --short HEAD)

Notes:

• DSN is Sentry-format; projects are created in GlitchTip UI. Use per-environment DSNs when possible.
• Keep sampling conservative in production to avoid noise and cost.
• If you do not want PII, set SENTRY_SEND_DEFAULT_PII=false in Laravel config (or handle in config/sentry.php).
• For source map uploads via the Vite plugin, also set: SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT, SENTRY_URL=https://logsder.fotospiel.app.

2) Backend (Laravel 12, PHP 8.3)

1. Install SDK: composer require sentry/sentry-laravel.
2. (Optional) Publish config: php artisan vendor:publish --provider="Sentry\\Laravel\\ServiceProvider" --tag="config" → tweak config/sentry.php (environment, sample rates, PII).
3. Context enrichment (recommended):
   • In app/Exceptions/Handler.php, set user (id, email) and tenant/event IDs on the Sentry scope.
   • Drop noisy 4xx exceptions via shouldReport or by ignoring HttpException with status < 500.
4. Health check: run php artisan sentry:test (sends a test event).
5. Queue/CLI: the DSN is forwarded to workers via the shared env anchor, so job failures also report.

3) Frontend (React 19 / Vite 7 PWAs)

1. Install SDKs: npm i @sentry/react @sentry/vite-plugin @sentry/tracing.
2. Initialize in each app entry (resources/js/guest/... and resources/js/admin/...):

import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.VITE_SENTRY_ENV,
  release: import.meta.env.VITE_SENTRY_RELEASE,
  tracesSampleRate: 0.05,
});

Wrap the root in <Sentry.ErrorBoundary> with a user-friendly fallback.

3. (Optional) Vite plugin for source maps:

import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  plugins: [
    react(),
    sentryVitePlugin({
      org: 'glitchtip',
      project: 'fotospiel-web',
      authToken: process.env.SENTRY_AUTH_TOKEN,
      url: 'https://logsder.fotospiel.app', // GlitchTip base
    }),
  ],
});

If you skip source map upload, events still work; stack traces will be minified.

4) Docker/Dokploy wiring

• docker-compose.dokploy.yml now forwards SENTRY_* and VITE_SENTRY_* to app, workers, scheduler, and docs-build.
• Ensure the build container that runs npm run build sees VITE_SENTRY_* (set in Dokploy env UI or .env loaded by Dokploy).
• Redeploy stack after setting envs; no other container changes needed.

5) Rollout / validation checklist

1. Set env vars for the target environment (production, staging).
2. Deploy containers.
3. Trigger test events:
   • Backend: php artisan sentry:test.
   • Frontend: throw a test error from console (Sentry.captureException(new Error('GlitchTip smoke test'))).
4. Verify events arrive in GlitchTip project at https://logsder.fotospiel.app.
5. Tune tracesSampleRate/profilesSampleRate after a day of traffic.

6) Hygiene & PII guardrails

• Do not attach raw request bodies or tokens. Scrub secrets in Sentry beforeSend hooks if added.
• Limit user context to non-sensitive identifiers (user id/email) and tenant/event IDs.
• Avoid logging photo metadata or guest names in breadcrumbs.

7) Troubleshooting

• No events: check DSN matches project and env vars are present in container (printenv | grep SENTRY).
• Minified stack traces: upload source maps via the Vite plugin or disable code splitting for critical bundles.
• High volume: drop sampling (tracesSampleRate, profilesSampleRate) and add ignore rules for expected 4xx.