Logger – Log Message Structure Concept

Status: CONCEPT · Created March 2026 Parent: COMP_logger_spec.md, GLOBAL_concept-ecosystem.md

Why a dedicated concept?

Log output is the most important debugging surface in operation. Inconsistent formats cost time — you search, filter, grep, and still don't immediately understand what happened.

This concept defines how a log message is structured, which fields are mandatory, which are optional, and how the format looks depending on context (browser vs. server, development vs. production).

Anatomy of a Log Message

Every log message consists of at most five parts:

1
[timestamp] (level) [module] message  |  key=value  key=value
2
─────────── ─────── ──────── ────────    ──────────────────────
3
     1          2      3         4               5 (optional)

1. Timestamp

Server (Node.js)

ISO 8601, UTC, milliseconds:

1
[2026-03-09T10:23:45.123Z]

Machine-readable, sortable, timezone unambiguous. No local format.

Client (Browser)

Time only, no date — a browser window doesn't live for days:

1
[10:23:45.123]

Shorter, more readable in the browser console.

2. Level

Always 5 characters wide — padded with spaces on the right. This keeps all lines aligned:

1
(debug)
2
(info )
3
(warn )
4
(error)

Four levels, no verbose, no trace, no fatal — deliberately minimalist.

No fatal — a fatal error throws an exception and terminates the process. That doesn't need to be logged, it's immediately obvious.

3. Module

The [module] part identifies where the message comes from — not what happened (the message itself handles that).

Convention

1
[package-name-without-xpulse-prefix]
2
[feature-slug]

Examples:

1
[controller]   ← @xpulse/controller
2
[router]       ← @xpulse/router
3
[template]     ← @xpulse/template
4
[http]         ← @xpulse/http
5
[logger]       ← @xpulse/logger itself
6
[session]      ← @xpulse/session / feature
7
[presence]     ← feature in client
8
[webrtc]       ← feature in client
9
[app]          ← @xpulse/app / entry point

Width

No fixed padding for the module — module names vary in length and padding would look ugly for long names. Instead: a consistent space after the closing ].

4. Message

The actual message. Lowercase, always English (Developer Layer — see GLOBAL_adr-013).

Rules

Short and concrete. A message describes an action or state — not a sentence, not an explanation, not context (that goes in the context part).

1
✓  route matched
2
✓  controller discovered
3
✓  navItem registered
4
✓  connection timeout
5
✗  A new route was successfully matched and the handler was called

Imperative or past participle — no questions, no exclamations:

1
✓  server started
2
✓  config loaded
3
✓  request failed
4
✗  server has been started!
5
✗  could not load config?

No values in the message — values belong in the context part:

1
✓  [controller] navItem registered  |  key=info_team  href=/info/team
2
✗  [controller] navItem info_team registered for /info/team

This makes grep on the message possible without stumbling over values.

5. Context (optional)

Structured additional info as key=value pairs, separated by |.

1
[2026-03-09T10:23:45.123Z] (info ) [http] request received  |  method=GET  path=/info  ip=192.168.1.0

Format Rules

• Separator: | (space, pipe, space) between message and context block
• Pairs: key=value without quotes unless the value contains spaces
• Order: most important first
• No comma, no JSON, no semicolon — only spaces between pairs

1
|  method=GET  path=/info/team  duration=12ms  status=200
2
|  key=info_team  href=/info/team  label="Team Nav"
3
|  controller=InfoController  method=team  path=/info/team

When to Use Context

Whenever a value is part of the event that you might want to filter or search for later. Rule of thumb: if you would grep for a value, it belongs in the context.

Full Examples

Server

1
[2026-03-09T10:23:44.001Z] (info ) [app]        server started  |  env=production  port=3000
2
[2026-03-09T10:23:44.012Z] (info ) [controller] ready  |  count=5  routes=8
3
[2026-03-09T10:23:44.013Z] (info ) [controller] navigation ready  |  items=5
4
[2026-03-09T10:23:45.001Z] (info ) [http]        request received  |  method=GET  path=/info  ip=192.168.1.0
5
[2026-03-09T10:23:45.008Z] (debug) [controller] controller called  |  controller=InfoController  method=index
6
[2026-03-09T10:23:45.010Z] (debug) [template]   render  |  view=info/index  duration=2ms
7
[2026-03-09T10:23:45.012Z] (info ) [http]        response sent  |  method=GET  path=/info  status=200  duration=11ms
8
[2026-03-09T10:23:46.001Z] (warn ) [controller] navItem duplicate key ignored  |  key=chat  file=src/controllers/support/chat.js  conflict=src/controllers/tool/chat.js
9
[2026-03-09T10:23:46.002Z] (error) [template]   render failed  |  view=info/broken  err=TemplateNotFound

Client (Browser Console)

1
[10:23:44.001] (info ) [session]  login successful  |  user=alice
2
[10:23:44.120] (debug) [presence] peer connected  |  peerId=b3f7a
3
[10:23:44.300] (info ) [router]   navigation  |  path=/peers
4
[10:23:48.001] (warn ) [webrtc]   ice candidate missing  |  peerId=b3f7a
5
[10:23:55.120] (error) [session]  decryption failed  |  key=chat_history

Format by Context

JSON Format (optional, production)

For log aggregators (e.g. Loki, Elasticsearch) the server logger can optionally output JSON — configurable via xpulse.json:

1
{
2
  "log": {
3
    "format": "json"
4
  }
5
}

The logger then writes one JSON line per entry (NDJSON):

1
{"timestamp":"2026-03-09T10:23:45.123Z","level":"info","module":"http","message":"response sent","context":{"method":"GET","path":"/info","status":200,"duration":11}}

Fields: timestamp, level, module, message, context (object, not string).

Default is always human-readable text — JSON only when explicitly configured.

What `log.create(module)` Returns

The module slug is set once during create() and automatically included in every message:

1
const log = logger.create('controller');
2
 
3
log.debug('navItem registered', { key: 'info_team', href: '/info/team' });
4
// → [2026-03-09T10:23:44.001Z] (debug) [controller] navItem registered  |  key=info_team  href=/info/team
5
 
6
log.warn('navItem duplicate key ignored', { key: 'chat', file: '...', conflict: '...' });
7
// → [2026-03-09T10:23:44.002Z] (warn ) [controller] navItem duplicate key ignored  |  key=chat  file=...  conflict=...

The second parameter log.debug(message, context?) is always a flat object — no nested structures. Anyone needing to log deeply nested data serialises it themselves and uses a single data=... key.

Separation from `@xpulse/debug`

@xpulse/logger writes log messages to console and file — it is the writer.

@xpulse/debug listens via the logger:write event to every log entry and collects it for the Web Profiler — it is the reader.

The format is identical. @xpulse/debug does not parse log messages — it receives the structured data directly via the event:

1
event.emit('logger:write', {
2
    level:     'debug',
3
    module:    'controller',
4
    message:   'navItem registered',
5
    context:   { key: 'info_team', href: '/info/team' },
6
    timestamp: new Date().toISOString(),
7
});

This means: the logger concept remains cleanly separated from the debug visualisation.