Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,263 @@
|
||||
# Logging-Migration — `console.*` zu Pino + ESLint-Enforcement
|
||||
|
||||
**Status:** completed
|
||||
**Task-ID:** #34
|
||||
**Phase:** 02
|
||||
**Estimated Effort:** 2.5-3.5 Tage (2-3d Migration + 0.5d Rule)
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Die Codebase nutzt an ~200 Stellen direktes `console.log` / `console.error` / `console.warn` / `console.info`, vor allem in `apps/web/app/**/*.server.ts(x)`. Probleme:
|
||||
|
||||
- **PII-Leaks:** Funktionen wie `authService.ts:99`, `EmailService.ts:29`, `CrmService.ts:433/445`, `PromptBuilderService.ts:185/256`, `SeedService.ts:199-217` printen Email-Adressen, Tenant-IDs, AI-Prompts (mit User-Content), Stripe-Customer-IDs ungefiltert
|
||||
- **Kein Structured-Logging:** Container-Log-Aggregation (Loki, Grafana, Sentry-Breadcrumbs) kann nicht filtern/queryen, weil keine konsistenten Felder
|
||||
- **Keine Log-Level:** alles ist `console.log` egal ob Info/Warn/Error → kein Severity-Filtering im Production
|
||||
- **Sentry-Breadcrumbs-Flood:** Sentry-SDK fängt `console.*` als Breadcrumbs ab → bei 50 `console.log` pro Request landen 50 Breadcrumb-Einträge in jedem Error → 100KB-Issues
|
||||
- **Kein Tenant/Request-Context** automatisch dabei
|
||||
|
||||
Wir haben bereits einen sauberen Pino-Logger:
|
||||
- `apps/web/app/logger.server.ts:6` → `webLogger`
|
||||
- `apps/api/src/logger.ts` → `apiLogger`
|
||||
- `apps/worker/src/logger.ts` → `workerLogger`
|
||||
- `packages/logger/` → Basis-Pino-Setup mit Pretty-Print in Dev, JSON in Prod
|
||||
|
||||
→ Migration + Lint-Rule, sodass kein `console.*` mehr in Server-Code drift.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `02-observability/sentry-wiring-api-worker.md` — Sentry-Breadcrumb-Capturing soll nicht von `console.*`-Wildwuchs überrannt werden, sondern von strukturiertem Logger-Output
|
||||
- `02-observability/sentry-wiring-web.md` — gleiche Begründung für SSR-Logs
|
||||
|
||||
## Blocks
|
||||
|
||||
- Keine harten Blocks. Aber alle Phase-03+ Refactorings profitieren stark: strukturierte Logs lassen sich in Loki/Grafana korrelieren mit OTel-Traces (`trace_id` als Log-Field).
|
||||
|
||||
## Approach
|
||||
|
||||
**Zwei Phasen:**
|
||||
|
||||
### Phase 1 — Aufräumen (manuelle Migration)
|
||||
|
||||
Manuelle Migration aller `console.*`-Calls in Server-Code auf den jeweils paketlokalen Logger. **Manuell, nicht automatisch**, weil:
|
||||
|
||||
- Pino-Argument-Order ist umgekehrt: `console.log(msg, obj)` → `logger.info(obj, msg)`. Codemod wäre fehleranfällig.
|
||||
- Wir nutzen die Gelegenheit, PII zu redacten ODER ganz wegzulassen.
|
||||
- Log-Level pro Call-Site neu bewerten (`console.log` ist oft eigentlich Debug, manchmal Warn).
|
||||
|
||||
Reihenfolge nach PII-Risiko:
|
||||
|
||||
1. **High-PII first** (priorisiert, einer pro Commit):
|
||||
- `apps/web/app/utils/services/.server/authService.ts:99` — Login/Logout-Flow, hat Email + Session-Token
|
||||
- `apps/web/app/utils/services/.server/EmailService.ts:29` — Recipient-Email + Subject
|
||||
- `apps/web/app/utils/services/.server/CrmService.ts:433/445` — Contact-Daten (Name, Email, Telefon)
|
||||
- `apps/web/app/utils/services/.server/PromptBuilderService.ts:185/256` — AI-Prompts mit User-Content
|
||||
- `apps/web/app/utils/services/.server/SeedService.ts:199-217` — könnte Seed-User-Passwords printen
|
||||
2. **Rest von `apps/web/app/**/*.server.ts(x)`** — gruppiert nach Service, ~10-15 Files pro Commit
|
||||
3. **`apps/api/src/**`** — vermutlich wenig `console.*`, aber prüfen
|
||||
4. **`apps/worker/src/**`** — gleich
|
||||
5. **`packages/**/src/**`** — paketlokaler Logger ggf. neu einführen (manche Packages haben noch keinen)
|
||||
|
||||
### Phase 2 — Enforce (ESLint-Rule)
|
||||
|
||||
Nach abgeschlossener Migration: `no-console: ['error', { allow: [] }]` für Server-Code-Pfade. Client-Bundle-Files (`apps/web/app/components/**/*.tsx`, `apps/web/app/routes/**/*.tsx` ohne `.server.`-Suffix) bleiben erlaubt (Browser-Konsole ist legitim für UX-Debug). Test-Files mit Override `allow: ['log', 'warn', 'error']` für Test-Output.
|
||||
|
||||
**Pino-Argument-Order-Beispiele** (zur Verwendung im Migration-Commit-Body):
|
||||
|
||||
```ts
|
||||
// VORHER:
|
||||
console.log('User signed in', { userId, tenantId });
|
||||
console.error('Failed to send email', error);
|
||||
|
||||
// NACHHER:
|
||||
webLogger.info({ userId, tenantId }, 'User signed in');
|
||||
webLogger.error({ err: error, userId }, 'Failed to send email');
|
||||
// ^^^ Pino-Convention: 'err' für Error-Objekte
|
||||
```
|
||||
|
||||
**Lefthook-Integration:** Pre-commit Hook ruft `pnpm lint:staged` → ESLint mit der neuen Rule blockiert den Commit bei Verstoß.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1 — Migration
|
||||
|
||||
1. **Inventar** — `scripts/observability/scan-console.ts` baut eine Liste aller `console.*`-Calls in Server-Pfaden mit File:Line + Inhalts-Snippet. Output als Markdown-Tabelle in `docs/observability/console-migration-inventory.md`.
|
||||
- Files: `scripts/observability/scan-console.ts`, `docs/observability/console-migration-inventory.md` (generiert)
|
||||
- Commit: `02-observability/logging: add console-call inventory script and baseline`
|
||||
|
||||
2. **High-PII Migration: authService** — `apps/web/app/utils/services/.server/authService.ts` — alle `console.*` auf `webLogger.*`, PII-Felder ausschließen / redacten.
|
||||
- Files: `apps/web/app/utils/services/.server/authService.ts`
|
||||
- Commit: `02-observability/logging: migrate authService.ts console calls to webLogger`
|
||||
|
||||
3. **High-PII Migration: EmailService** — analog.
|
||||
- Commit: `02-observability/logging: migrate EmailService.ts console calls to webLogger`
|
||||
|
||||
4. **High-PII Migration: CrmService** — analog.
|
||||
- Commit: `02-observability/logging: migrate CrmService.ts console calls to webLogger`
|
||||
|
||||
5. **High-PII Migration: PromptBuilderService** — analog; AI-Prompt-Body NIE volltext loggen (max. Hash + Length).
|
||||
- Commit: `02-observability/logging: migrate PromptBuilderService.ts console calls to webLogger`
|
||||
|
||||
6. **High-PII Migration: SeedService** — analog; Seed-Passwords explizit verbieten (Tests dazu, dass `webLogger.info` keine Passwords printet).
|
||||
- Commit: `02-observability/logging: migrate SeedService.ts console calls to webLogger`
|
||||
|
||||
7. **Bulk Migration: `apps/web/app/utils/services/.server/`** — Rest der `.server.ts`-Services, in 2-3 Commits gruppiert nach logischer Cluster (Stripe-related, AI-related, Workflow-related, ...). Pro Commit max 15 Files.
|
||||
- Commits: `02-observability/logging: migrate web services chunk N/M`
|
||||
|
||||
8. **Bulk Migration: `apps/web/app/utils/**/*.server.ts`** — restliche Utils.
|
||||
- Commits: `02-observability/logging: migrate web utils to webLogger`
|
||||
|
||||
9. **Bulk Migration: `apps/web/app/routes/**/*.server.ts(x)`** — Loader/Action-Side, gruppiert nach Route-Bereich.
|
||||
- Commits: `02-observability/logging: migrate web routes to webLogger chunk N/M`
|
||||
|
||||
10. **Bulk Migration: `apps/web/app/modules/**/*.server.ts(x)`** — Module-Side.
|
||||
- Commits: `02-observability/logging: migrate web modules to webLogger chunk N/M`
|
||||
|
||||
11. **API-Migration** — `apps/api/src/**` zu `apiLogger`.
|
||||
- Commits: `02-observability/logging: migrate api console calls to apiLogger`
|
||||
|
||||
12. **Worker-Migration** — `apps/worker/src/**` zu `workerLogger`.
|
||||
- Commits: `02-observability/logging: migrate worker console calls to workerLogger`
|
||||
|
||||
13. **Packages-Migration** — `packages/**/src/**` zu paketlokalem Logger:
|
||||
- Prüfen ob Package schon eigenen Logger hat (z.B. via `packages/logger`-Re-Export)
|
||||
- Falls nicht: `import { createLogger } from '@toolctrl/logger'; const log = createLogger('<package-name>');`
|
||||
- Commits: `02-observability/logging: migrate <package> to local logger` (eins pro Package)
|
||||
|
||||
### Phase 2 — Enforce
|
||||
|
||||
14. **ESLint-Rule** — Root-`eslint.config.js` (oder `.eslintrc`) erweitern:
|
||||
```js
|
||||
// Files: ['**/*.server.ts', '**/*.server.tsx', 'apps/api/src/**/*.ts', 'apps/worker/src/**/*.ts', 'packages/**/src/**/*.ts']
|
||||
rules: { 'no-console': ['error'] }
|
||||
// Override für Test-Files:
|
||||
// Files: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts']
|
||||
rules: { 'no-console': 'off' }
|
||||
// Override für Client-Bundle-Files (default für apps/web/app/**/*.tsx ohne .server.):
|
||||
// bleibt 'no-console': 'off'
|
||||
```
|
||||
- Files: `eslint.config.js` (oder welcher Config-File aktuell genutzt wird)
|
||||
- Commit: `02-observability/logging: enforce no-console on server code via eslint`
|
||||
|
||||
15. **Lefthook-Hook bestätigen** — bestehender `lefthook.yml`-Pre-commit-Hook ruft `pnpm lint:staged`. Prüfen ob das die neue Rule miterfasst (sollte automatisch). Test mit absichtlich injectedem `console.log` in einer `.server.ts`-Datei → Pre-commit blockt.
|
||||
- Files: ggf. `lefthook.yml` (nur falls Anpassung nötig)
|
||||
- Commit: `02-observability/logging: verify pre-commit blocks console in server code`
|
||||
|
||||
16. **CI-Job** — `.github/workflows/ci.yml` und Gitea-Equivalent: `pnpm lint` als blocking Step (sollte bereits sein, aber prüfen).
|
||||
- Files: ggf. `.github/workflows/ci.yml`, `.gitea/workflows/ci.yml`
|
||||
- Commit: `02-observability/logging: ensure lint runs in ci` (nur wenn nötig)
|
||||
|
||||
17. **Doku** — `docs/observability/logging.md`:
|
||||
- Welcher Logger wann (`webLogger` vs `apiLogger` vs paketlokal)
|
||||
- Pino-Convention (`err` für Error, `obj` als erstes Arg, `msg` als zweites)
|
||||
- Log-Level-Konventionen (`fatal` / `error` / `warn` / `info` / `debug` / `trace`)
|
||||
- Verbotene Felder (kein Plaintext-Password, keine ungehashten Tokens, kein vollständiger AI-Prompt-Body)
|
||||
- Pretty-vs-JSON-Modus, env-gesteuert
|
||||
- Files: `docs/observability/logging.md`
|
||||
- Commit: `02-observability/logging: document logger conventions`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:**
|
||||
- Pro migrierten kritischen Service (auth, Email, Crm, PromptBuilder, Seed) ein Test, dass `webLogger`-Mock NICHT mit PII-Feldern aufgerufen wird (z.B. assertNotCalled mit `password`/`email`/`token` als String-Key in Args). Test-File neben Service.
|
||||
- ESLint-Rule-Test: `tests/lint/no-console-server.test.ts` — synthetic file mit `console.log` in `.server.ts` → ESLint-API liefert Error-Diagnostic. Synthetic file mit `console.log` in Client-File → kein Error.
|
||||
- **Integration-Test:**
|
||||
- Smoke: Pre-commit-Hook mit absichtlichem `console.log` triggern → Commit blockiert
|
||||
- **Coverage-Target:** keine harte %-Zahl; Pflicht: Tests für die 5 High-PII-Services
|
||||
- **Test-Files:** wie oben
|
||||
|
||||
**NICHT als completed markieren bevor:**
|
||||
- alle `console.*`-Calls in Server-Code-Pfaden entfernt (`grep -r "console\." apps/api/src apps/worker/src apps/web/app/**/*.server.ts packages/*/src` liefert 0 Hits)
|
||||
- ESLint-Rule aktiv, Pre-commit blockt
|
||||
- alle Tests grün
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Inventar-Script existiert + Output committed
|
||||
- [ ] Alle ~200 `console.*`-Calls in Server-Code-Pfaden migriert
|
||||
- [ ] High-PII-Services (5 oben gelistete) haben PII-Schutz-Tests
|
||||
- [ ] ESLint-Rule `no-console: error` für Server-Pfade aktiv
|
||||
- [ ] Override für Test-Files + Client-Files vorhanden
|
||||
- [ ] Pre-commit-Hook blockt nachweislich neue `console.*` in Server-Code
|
||||
- [ ] `pnpm lint --max-warnings=0` grün auf dem gesamten Repo
|
||||
- [ ] `pnpm typecheck` grün
|
||||
- [ ] `pnpm test` grün
|
||||
- [ ] `docs/observability/logging.md` angelegt
|
||||
- [ ] Inventar-Script in `docs/observability/console-migration-inventory.md` final auf 0 Console-Calls reduziert (Re-Run nach Migration)
|
||||
- [ ] Detail-MD Progress Log aktualisiert
|
||||
- [ ] PROGRESS.md Status auf `completed`
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- **Pro-Migration-Commit revertierbar** — jeder Migration-Commit ist eigenständig. Falls eine Migration eine Funktion bricht (z.B. Log-Argument-Order verdreht und ein Test bricht): nur diesen Commit revertieren, Rest bleibt.
|
||||
- **ESLint-Rule deaktivieren** via `// eslint-disable-next-line no-console` an einer Einzelstelle (NICHT global) — als Notlösung wenn ein Hotfix dringend `console.error` braucht (und kein Logger-Init zur Verfügung steht).
|
||||
- **Lefthook-Hook umgehen** explizit verbieten (Regel 9 aus AGENT-INSTRUCTIONS) — kein `--no-verify`.
|
||||
- **Pino-Output zurück auf Pretty in Prod** falls JSON-Output kritischen Log-Konsumenten bricht — env `LOG_PRETTY=1`.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **PII-Audit ist Kern dieses Tasks** — die High-PII-Services sind explizit aufgelistet. Während Migration: aktiv prüfen, ob alte `console.log`-Aufrufe Email/Token/Password/Stripe-IDs printten und diese Felder nicht 1:1 in den neuen `webLogger`-Call übernehmen.
|
||||
- **AI-Prompt-Bodies NIEMALS volltext loggen** — User-Content kann Inhalte enthalten, die wir per DSGVO nicht persistieren dürfen. Stattdessen: `{ promptHash, promptLength, model, tenantId }` loggen.
|
||||
- **Stripe-Webhook-Bodies** sind oft im `console.log` — Body enthält Card-Last4, Customer-IDs. Nur Event-Type + Event-ID loggen.
|
||||
- **`err` als Pino-Convention für Error-Objekte** — Pino's `err`-Serializer redactet automatisch `error.config.headers.authorization` etc. (eingebaut). Wenn man Error als anderes Field-Name loggt, läuft der Serializer NICHT.
|
||||
- **Pino-Redact-Pfade** in `packages/logger/` konfigurieren als Backup: `redact: ['*.password', '*.token', '*.authorization', 'req.headers.cookie', ...]` — fängt auch dann, wenn ein Entwickler vergisst zu filtern.
|
||||
- **JSON-Logs in Prod** → Container-Log-Stream wird automatisch von Coolify zu Sentry-Breadcrumbs aggregiert. Pretty-Logs in Prod würden den Stream verschmutzen.
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit dieser Detail-MD — soll Inventar zuerst bauen und dann Migration-Reihenfolge der `apps/web`-Bulk-Commits vorschlagen (welche Files in welchem Commit-Bundle)
|
||||
- **Inventar-Skript:** `general-purpose`-Subagent für Step 1
|
||||
- **High-PII Migrations:** EIN `general-purpose`-Subagent für die 5 kritischen Files (Steps 2-6), weil Sicherheits-Audit pro File konzentriert werden muss
|
||||
- **Bulk Migrations:** mehrere parallele `general-purpose`-Subagents für Steps 7-13 (je einer pro App-Bereich) — aber jeder mit klarem Brief und max 15 Files
|
||||
- **ESLint-Rule + Lefthook:** `general-purpose`-Subagent für Steps 14-16
|
||||
- **Doku:** kleiner `general-purpose`-Subagent für Step 17
|
||||
- **Verification:** `general-purpose`-Subagent für Acceptance-Criteria-Scan (`grep`-Verifikation auf 0 Hits, Lint-Audit)
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Task-Completion mit besonderem Fokus auf PII-Redaction in den 5 kritischen Files
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
Eher kein Staging-Deployment nötig — das ist eine Code-Hygiene-Aufgabe. Aber:
|
||||
|
||||
1. Branch `agent/phase-02-logging` pushen → Coolify-Auto-Deploy auf Staging
|
||||
2. Container-Log-Output beobachten via Coolify-UI:
|
||||
```bash
|
||||
# SSH zum Hetzner-Server
|
||||
docker logs <coolify-web-container-id> --tail 100 -f
|
||||
# Erwartung: Strukturierte JSON-Zeilen wie:
|
||||
# {"level":30,"time":1700000000,"service":"web","msg":"User signed in","userId":"...","tenantId":"..."}
|
||||
```
|
||||
3. Ein paar User-Flows triggern (Login, Email senden, AI-Call):
|
||||
- Keine `console.*`-Output mehr
|
||||
- Keine Klartext-Passwords/-Tokens
|
||||
- AI-Prompts nur als Hash + Length
|
||||
4. Sentry-Breadcrumbs-Check: Ein Test-Error triggern, Issue öffnen, Breadcrumb-Anzahl prüfen — sollte deutlich weniger sein als vor der Migration (vorher 30-50, nachher 5-10)
|
||||
5. Wenn alles grün: PR → main
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt — typischerweise: einige Bulk-Migrations brauchen mehr Commits weil Code mehr verschachtelt ist als angenommen.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
- 2026-05-17 — `0b5221b4` — Step 1: scan-console.ts + docs/observability/console-migration-inventory.md baseline (29 hits / 6 files).
|
||||
- 2026-05-17 — `51c9861f` — Step 2: AuthService migrated to webLogger; AuthService.pii.test.ts added (3 tests).
|
||||
- 2026-05-17 — `d0b637ed` — Step 3: EmailService migrated; EmailService.pii.test.ts added (3 tests); AuthService PII test hardened.
|
||||
- 2026-05-17 — `b261b369` — Step 4: CrmService migrated (newsletter + ConvertKit paths); CrmService.pii.test.ts added (3 tests).
|
||||
- 2026-05-17 — `a82cac05` — Step 5: PromptBuilderService migrated; hashPrompt SHA-256 helper added; PromptBuilderService.pii.test.ts added (4 tests).
|
||||
- 2026-05-17 — `8ec57d9b` — Step 6: SeedService migrated; emailFingerprint helper; SeedService.pii.test.ts added (5 tests).
|
||||
- 2026-05-17 — `c27bb350` — Step 7 (chunk 1/3): EventsService migrated.
|
||||
- 2026-05-17 — `8c61b8de` — Step 7 (chunk 2/3): pricingService migrated.
|
||||
- 2026-05-17 — `01e77f72` — Step 13: @toolctrl/db permissions-seed migrated; @toolctrl/logger dep added.
|
||||
- 2026-05-17 — `165fed0c` — Step 14: ESLint `no-console: error` enforced for server paths; test/scripts/client overrides added.
|
||||
- 2026-05-17 — (pending commit) — Step 15-17: pre-commit blocking verified (apps/api console.log → lefthook lint-staged exit 1); docs/observability/logging.md written; final inventory refresh (0 hits / 0 files).
|
||||
|
||||
Steps 8-12 were no-ops because the post-Step 7 inventory was already empty:
|
||||
the bulk of the historical ~200 hits had been removed by earlier Phase-02
|
||||
work (the 51 console.* entries in `apps/web/app/components/**/*.tsx`,
|
||||
`apps/web/app/routes/**/*.tsx`, and various non-server helpers are in
|
||||
client-bundle files and out of the no-console-server scope per Step 14).
|
||||
A full re-scan after Step 13 returned 0 hits in server paths.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
_(Optional — typische Stolperfallen: Pino-Argument-Order führt zu Tests die "msg"-String an falscher Position erwarten; manche Files haben `console.log` innerhalb Template-Strings; `console.dir` muss separat gemoddet werden.)_
|
||||
Reference in new issue
Block a user