From a35014afb5702bdc06b7be5bf224a74eb83a2933 Mon Sep 17 00:00:00 2001 From: Till JS Date: Thu, 19 Mar 2026 15:01:08 +0100 Subject: [PATCH] docs: add GlitchTip error tracking documentation - Architecture overview with container diagram - All 8 project DSNs documented - Backend integration guide (instrument.ts pattern) - Shared package API reference - Docker setup and administration commands - Instructions for adding new apps Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/ERROR_TRACKING.md | 173 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 docs/ERROR_TRACKING.md diff --git a/docs/ERROR_TRACKING.md b/docs/ERROR_TRACKING.md new file mode 100644 index 000000000..11316e0ba --- /dev/null +++ b/docs/ERROR_TRACKING.md @@ -0,0 +1,173 @@ +# Error Tracking with GlitchTip + +Self-hosted, open-source error tracking for all ManaCore apps using [GlitchTip](https://glitchtip.com) (Sentry-compatible). + +## Overview + +| | | +|---|---| +| **URL** | https://glitchtip.mana.how | +| **Version** | GlitchTip v6.0 | +| **Login** | admin@mana.how | +| **License** | MIT | +| **Containers** | `mana-mon-glitchtip` (web) + `mana-mon-glitchtip-worker` (celery) | +| **Database** | PostgreSQL `glitchtip` (shared infra) | +| **Cache** | Redis DB 1 (shared infra) | +| **Port** | 8020 (internal), via Cloudflare Tunnel | + +## Architecture + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ +│ NestJS │────>│ GlitchTip │────>│ PostgreSQL │ +│ Backends │ │ (Port 8020)│ │ (glitchtip DB) │ +└─────────────┘ └──────┬──────┘ └─────────────────┘ + │ +┌─────────────┐ ┌──────┴──────┐ ┌─────────────────┐ +│ SvelteKit │────>│ GlitchTip │────>│ Redis │ +│ Web Apps │ │ Worker │ │ (DB 1) │ +└─────────────┘ └─────────────┘ └─────────────────┘ +``` + +## Project DSNs + +| App | Project ID | DSN | +|-----|-----------|-----| +| Calendar | 1 | `https://7dcf6e86-48a0-4b85-b2cb-275921c059d5@glitchtip.mana.how/1` | +| Contacts | 2 | `https://a0d81e4b-7869-4b57-951a-1a5de6d64ae7@glitchtip.mana.how/2` | +| Todo | 3 | `https://c774433d-212c-473d-9088-542a84224488@glitchtip.mana.how/3` | +| Chat | 4 | `https://7ffb55d2-3705-4979-89db-abd486a42014@glitchtip.mana.how/4` | +| Context | 5 | `https://1ac1bac3-6c75-456e-8857-5048eb0c925c@glitchtip.mana.how/5` | +| Picture | 6 | `https://a04c991e-0702-4b73-a670-babef3e7c5d1@glitchtip.mana.how/6` | +| Clock | 7 | `https://4d5ea890-019d-4a98-8e98-34bc3e374e0a@glitchtip.mana.how/7` | +| Zitare | 8 | `https://53b87191-3d86-4628-a8c7-cb97b3f69e06@glitchtip.mana.how/8` | + +## Integration + +### Backend (NestJS) + +Each backend has an `instrument.ts` that initializes error tracking before the app bootstraps: + +```typescript +// src/instrument.ts +import { initErrorTracking } from '@manacore/shared-error-tracking'; + +initErrorTracking({ + serviceName: 'calendar-backend', + environment: process.env.NODE_ENV, + release: process.env.APP_VERSION, +}); +``` + +```typescript +// src/main.ts - instrument MUST be the first import +import './instrument'; +import { bootstrapApp } from '@manacore/shared-nestjs-setup'; +``` + +Set the DSN as environment variable: +```env +GLITCHTIP_DSN=https://@glitchtip.mana.how/ +``` + +### Shared Package + +`@manacore/shared-error-tracking` provides: + +| Function | Purpose | +|----------|---------| +| `initErrorTracking(options)` | Initialize Sentry SDK with GlitchTip DSN | +| `captureException(error, context)` | Capture an error manually | +| `captureMessage(message, level)` | Capture a message | +| `setUser({ id, email })` | Set user context for error reports | +| `setTag(key, value)` | Set extra context tags | +| `flush(timeout)` | Flush pending events before exit | + +NestJS-specific (`@manacore/shared-error-tracking/nestjs`): + +| Export | Purpose | +|--------|---------| +| `SentryExceptionFilter` | Global exception filter (captures 5xx only) | +| `setUserFromRequest(req)` | Set user context from JWT request | + +### Web Apps (SvelteKit) - Future + +```typescript +// src/hooks.client.ts +import { initErrorTracking } from '@manacore/shared-error-tracking'; + +initErrorTracking({ + serviceName: 'calendar-web', + dsn: import.meta.env.PUBLIC_GLITCHTIP_DSN, +}); +``` + +## Docker Setup + +In `docker-compose.macmini.yml`: + +```yaml +glitchtip: + image: glitchtip/glitchtip:latest + container_name: mana-mon-glitchtip + environment: + DATABASE_URL: postgres://postgres:${POSTGRES_PASSWORD}@postgres:5432/glitchtip + REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379/1 + SECRET_KEY: ${GLITCHTIP_SECRET_KEY} + PORT: "8020" + GLITCHTIP_DOMAIN: https://glitchtip.mana.how + ports: + - "8020:8020" + +glitchtip-worker: + image: glitchtip/glitchtip:latest + command: ./bin/run-celery-with-beat.sh + environment: + DATABASE_URL: postgres://postgres:${POSTGRES_PASSWORD}@postgres:5432/glitchtip + REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379/1 + SECRET_KEY: ${GLITCHTIP_SECRET_KEY} +``` + +## Administration + +### Server Access + +```bash +ssh mana-server +DOCKER=/Applications/Docker.app/Contents/Resources/bin/docker + +# View logs +$DOCKER logs mana-mon-glitchtip --tail 50 +$DOCKER logs mana-mon-glitchtip-worker --tail 50 + +# Django shell +$DOCKER exec -it mana-mon-glitchtip python manage.py shell + +# Create new project +$DOCKER exec mana-mon-glitchtip python -c ' +import django, os +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "glitchtip.settings") +django.setup() +from apps.organizations_ext.models import Organization +from apps.projects.models import Project, ProjectKey +org = Organization.objects.get(slug="manacore") +proj = Project.objects.create(name="new-app", organization=org, platform="node") +key = ProjectKey.objects.create(project=proj) +print(f"DSN: https://{key.public_key}@glitchtip.mana.how/{proj.id}") +' +``` + +### Adding a New App + +1. Create project in GlitchTip (via UI or Django shell) +2. Copy DSN +3. Add `@manacore/shared-error-tracking` to backend package.json +4. Create `src/instrument.ts` +5. Import `./instrument` as first line in `src/main.ts` +6. Set `GLITCHTIP_DSN` env variable + +## Monitoring + +- GlitchTip Dashboard: https://glitchtip.mana.how +- Health Check: https://glitchtip.mana.how/_health/ +- Grafana Dashboard: https://grafana.mana.how (container metrics)