GlitchTip — błędy aplikacji

GlitchTip (glitchtip.acepark.pl) zbiera błędy z serwera, z crona i z przeglądarki, grupuje je w „issues” i wysyła alert e-mail. To odpowiednik Sentry utrzymywany na naszym VPS; aplikacja rozmawia z nim przez @sentry/nextjs.

👤 Dla pracownika

Co widzisz w alercie

Mail „[GlitchTip] New issue in acepark” zawiera:

• tytuł — typ i komunikat błędu, np. Error: Payment webhook verification failed,
• environment — production, qa albo dev; reaguj na production, pozostałe to środowiska testowe,
• release — skrót commita, który był wdrożony (ten sam widać w /api/health),
• link do issue.

Jedno issue to jedna klasa błędu; licznik „events” mówi, ile razy wystąpił, a „users” — ilu użytkowników dotknął.

Co zrobić

1. Jeśli klient zgłosił problem, poproś, żeby użył przycisku „Zgłoś błąd” na ekranie błędu. Powstaje zgłoszenie w Jirze z datą, adresem strony, identyfikatorem błędu i linkiem do zdarzenia w GlitchTipie — bez tego trzeba szukać ręcznie.
2. Błędy przejściowe (utrata połączenia, SQLITE_BUSY, anulowane żądanie) są ponawiane automatycznie i nie trafiają do GlitchTipa. Jeśli issue mimo to rośnie w oczach, to nie jest chwilowe.
3. Rozwiązane issue oznacz jako „Resolved”. Jeśli błąd wróci po kolejnym wdrożeniu, GlitchTip sam je otworzy ponownie (regresja).

Logowanie: adres jest za Cloudflare Access — najpierw kod jednorazowy na e-mail @acepark.pl, potem konto GlitchTip (zaproszenie od administratora, samodzielna rejestracja jest wyłączona).

🔧 Dokumentacja techniczna

Skąd trafiają zdarzenia

Źródło	Co wysyła
lib/logger.ts → reportToSentry	każdy logError(...) — z tagiem context, user.id (gdy jest aktor żądania) i extra = metadane wpisu. Tabela logs dostaje ten sam wpis; GlitchTip dokłada stack trace i grupowanie
instrumentation.ts → onRequestError	błędy renderowania i Server Actions, których nie złapał żaden error.tsx
app/global-error.tsx	błędy root layoutu
instrumentation-client.ts	błędy w przeglądarce i przejścia routera (captureRouterTransitionStart)

Serwer i cron inicjalizują SDK w sentry.server.config.ts (przez register() w instrumentation.ts), przeglądarka w instrumentation-client.ts. Wspólne opcje są w lib/sentry-options.ts.

Środowisko i wersja

Pole	Skąd
environment	SENTRY_ENVIRONMENT (serwer) / NEXT_PUBLIC_SENTRY_ENVIRONMENT (przeglądarka, wkompilowane przy buildzie)
release	APP_RELEASE = ${SOURCE_COMMIT} z Coolify — wymaga include_source_commit_in_build (patrz infrastruktura-vps.md)
DSN	SENTRY_DSN (serwer) / NEXT_PUBLIC_SENTRY_DSN (przeglądarka); DSN jest kluczem publicznym

Jest jeden projekt acepark; środowiska rozróżnia tag environment. W next dev i w testach @sentry/nextjs jest podmieniane na lib/sentry-noop.ts (te same eksporty, nic nie wysyła), więc lokalnie nic nie trafia do GlitchTipa.

Filtr szumu (beforeSend)

lib/sentry-options.ts odrzuca:

• wzorce przejściowe z lib/utils/transient-error.ts (utrata połączenia, SQLITE_BUSY, Connection closed…) — te błędy są ponawiane, a zgłaszanie ich zasypywałoby projekt,
• NEXT_NOT_FOUND, NEXT_REDIRECT, AbortError, ResizeObserver loop,
• błędy, których wszystkie ramki stosu pochodzą z rozszerzeń przeglądarki (chrome-extension:// itp.), a żadna z /_next/.

beforeSendTransaction wycina transakcje opisujące sam transport do GlitchTipa (POST …/envelope/), inaczej byłyby najliczniejszą „trasą”. tracesSampleRate pochodzi z SENTRY_TRACES_SAMPLE_RATE (0 = wyłączone; nierozpoznana wartość wyłącza, nie włącza). sendDefaultPii=false.

Zgłoszenie z aplikacji → Jira → GlitchTip

reportServerError (lib/actions/report-server-error.ts) tworzy zgłoszenie w Jirze z prawdziwym komunikatem i stackiem serwera (rejestr lib/server-error-registry.ts po digest), a lib/glitchtip-link.ts dokłada link ${GLITCHTIP_URL}/${GLITCHTIP_ORGANIZATION}/issues/?query=<eventId> z Sentry.lastEventId(). Bez DSN link zamienia się w sam identyfikator albo „brak (zdarzenie nie zostało wysłane)”.

Jak czytać issue

1. Tags → context to nazwa modułu z logError (np. payments/webhook), environment, release.
2. Additional data → metadane wpisu logu (identyfikatory, kwoty — bez PII).
3. Breadcrumbs / Request → dla błędów z żądania: ścieżka, metoda, nagłówki bez cookies.
4. Ten sam błąd w tabeli logs: SELECT * FROM logs WHERE created_at >= '<czas>' AND context = '<context>' na /data/acepark.db (kontener web, node -e z node:sqlite albo sqlite3 na hoście po skopiowaniu snapshotu).

Konfiguracja usługi

• Alert: jedna reguła na projekt — 1 zdarzenie w 1 minucie → e-mail do organizacji.
• Monitory uptime: GET https://klient.acepark.pl/api/health (200) i GET https://hc.acepark.pl/ping/ (oczekiwane 404, potwierdza, że Healthchecks żyje).
• Retencja zdarzeń nie jest ustawiona (GLITCHTIP_MAX_EVENT_LIFE_DAYS) — baza Postgres GlitchTipa rośnie; do ustawienia przy pierwszym problemie z miejscem.
• Po restarcie Redisa/Postgresa GlitchTipa trzeba zrestartować też kontener worker: scheduler nie podnosi się sam i alerty milkną (incydent 07.09.2026, opis w infrastruktura-vps.md).