@xpulse/logger – Component Spec

Status: CONCEPT · Updated March 2026 Source: Chat v1.3.0 code review Parent: GLOBAL_concept-ecosystem.md

Overview

Logging for browser and Node.js under a shared interface.

Two variants under one package:

Dependencies

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

Interface (shared)

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
// Shared API
10
log.debug('connection established', { peerId });
11
log.info('server started', { port: 3000 });
12
log.warn('timeout exceeded', { ms: 75000 });
13
log.error('unknown error', { err });

Configuration via @xpulse/config

xpulse.json:

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

.env:

1
LOG=true
2
DEBUG=false

Logger reads on startup:

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

Variant: client

How it works

• Log level calculated dynamically per call (not set once at load time)
• Default level: off – until config is loaded
• logger.setLevel(level) for external control (e.g. after /health response)
• Styled console output via %c formatter

Styled Output

1
[HH:MM:SS.mmm] (debug) [presence] connection established
2
[HH:MM:SS.mmm] (info ) [router]   navigating to /peers
3
[HH:MM:SS.mmm] (warn ) [webrtc]   ice candidate missing
4
[HH:MM:SS.mmm] (error) [session]  decryption failed

Colors:

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

Variant: server

How it works

• Level set once at startup (Node, no hot-reload needed)
• Rotating file log: max 10 MB, 5 files
  • Path: var/log/{NODE_ENV}.log (configurable)
• Dual output: file + console simultaneously
• IP anonymisation: active by default, full IPs only when DEBUG=true
  • IPv4: last octet → 0
  • IPv4-mapped IPv6: last octet → 0
  • IPv6: last group → 0
• GDPR: no personally identifiable data when LOG=false

Additional exports (server)

1
import logger from '@xpulse/logger/server';
2
 
3
logger.formatIp(ip);         // anonymised or full depending on DEBUG
4
logger.startup({ port });    // log startup summary

Log format (server)

1
[2026-03-09T10:23:45.123Z] (info ) xPulse Web started | 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

Package Structure

1
@xpulse/logger/
2
  client.js     ← browser variant
3
  server.js     ← Node variant
4
  levels.js     ← shared level constants (internal)
5
  README.md
6
  package.json

Debug Integration

When @xpulse/debug is installed as a devDependency, @xpulse/logger automatically provides a DataCollector. @xpulse/debug discovers it via node_modules/@xpulse/logger/src/datacollectors/ – no configuration needed.

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

The LoggerCollector (name: 'logger', icon: '📝') shows in the Web Profiler:

• Log Lines (logger-lines): all log entries for this request, newest first – formatted as [timestamp] (level) [module] message | data
• Log Files (table): snapshot of files under var/log/ with file size

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

Badge in the toolbar: total count + warnings/errors, e.g. 12 · ⚠ 2 · ✗ 1. Badge is only set when at least one log line is present.

Open Questions