@xpulse/logger – Component Spec

Status: CONCEPT · Aktualisiert März 2026 Quelle: Chat v1.3.0 Code-Review Übergeordnet: GLOBAL_concept-ecosystem.md

Übersicht

Logging für Browser und Node.js unter einem gemeinsamen Interface.

Zwei Varianten unter einem Paket:

Dependencies

1
@xpulse/logger
2
  └── @xpulse/config   ← log.level + log.enabled aus xpulse.json / .env

Interface (gemeinsam)

1
// Server
2
import logger from '@xpulse/logger/server';
3
const log = logger.create('signaling');
4
 
5
// Client
6
import logger from '@xpulse/logger/client';
7
const log = logger.create('presence');
8
 
9
// Gemeinsames API
10
log.debug('verbindung aufgebaut', { peerId });
11
log.info('server gestartet', { port: 3000 });
12
log.warn('timeout überschritten', { ms: 75000 });
13
log.error('unbekannter fehler', { err });

Konfiguration via @xpulse/config

xpulse.json:

1
{
2
  "log": {
3
    "level":   "info",
4
    "enabled": true
5
  }
6
}

.env:

1
LOG=true
2
DEBUG=false

Logger liest beim Start:

1
import logger from '@xpulse/logger/server';
2
 
3
await logger.init(); // liest config + .env

Variante: client

Funktionsweise

• Log-Level dynamisch pro Call berechnet (kein einmaliges Setzen beim Load)
• Default-Level: off – bis Config geladen ist
• logger.setLevel(level) für externe Steuerung (z.B. nach /health Response)
• Styled Console Output via %c Formatter

Styled Output

1
[HH:MM:SS.mmm] (debug) [presence] verbindung aufgebaut
2
[HH:MM:SS.mmm] (info ) [router]   navigiere zu /peers
3
[HH:MM:SS.mmm] (warn ) [webrtc]   ice candidate fehlt
4
[HH:MM:SS.mmm] (error) [session]  entschlüsselung fehlgeschlagen

Farben:

• debug → #7eb8a4 (accent2/mint)
• info → #aaa
• warn → #c0a060
• error → #c0606a

Variante: server

Funktionsweise

• Level einmalig beim Start gesetzt (Node, kein Hot-Reload nötig)
• Rotating File Log: max 10 MB, 5 Dateien
  • Pfad: var/log/{NODE_ENV}.log (konfigurierbar)
• Dual Output: Datei + Console gleichzeitig
• IP-Anonymisierung: standardmäßig aktiv, nur bei DEBUG=true vollständige IPs
  • IPv4: letztes Oktett → 0
  • IPv4-mapped IPv6: letztes Oktett → 0
  • IPv6: letzte Gruppe → 0
• DSGVO: bei LOG=false keine personenbezogenen Daten

Zusätzliche Exports (server)

1
import logger from '@xpulse/logger/server';
2
 
3
logger.formatIp(ip);         // anonymisiert oder vollständig je nach DEBUG
4
logger.startup({ port });    // Startup-Zusammenfassung loggen

Log-Format (server)

1
[2026-03-09T10:23:45.123Z] (info ) xPulse Web gestartet | ENV=production | PORT=3000
2
[2026-03-09T10:23:46.001Z] (info ) GET /privacy/ 200 12ms
3
[2026-03-09T10:23:47.220Z] (warn ) health check failed | source=chat

Paket-Struktur

1
@xpulse/logger/
2
  client.js     ← Browser-Variante
3
  server.js     ← Node-Variante
4
  levels.js     ← gemeinsame Level-Konstanten (intern)
5
  README.md
6
  package.json

Debug Integration

Wenn @xpulse/debug als devDependency installiert ist, stellt @xpulse/logger automatisch einen DataCollector bereit. @xpulse/debug discovert ihn via node_modules/@xpulse/logger/src/datacollectors/ – keine Konfiguration nötig.

1
"optionalDependencies": {
2
  "@xpulse/debug": "^1.0.0"
3
}

Der LoggerCollector (name: 'logger', icon: '📝') zeigt im Web Profiler:

• Log Lines (logger-lines): alle Log-Einträge dieses Requests, neueste oben – formatiert als [timestamp] (level) [module] message | data
• Log Files (table): Snapshot der Dateien unter var/log/ mit Dateigröße

Level-Farben: debug → --accent2, info → --text, warn → #c0a060, error → --danger

Badge in der Toolbar: Gesamtanzahl + Warnungen/Fehler, z.B. 12 · ⚠ 2 · ✗ 1. Badge wird nur gesetzt wenn mindestens eine Log-Zeile vorhanden ist.

Offene Fragen