API

Trace ID Workflow

1. @xpulse/http generates a traceId per request.
2. traceId is attached to req.traceId and emitted in http:* events.
3. @xpulse/controller forwards it into templates as _traceId.
4. @xpulse/template includes traceId in render events.
5. @xpulse/debug aggregates everything per trace and stores it under var/cache/debug/_<traceId>/.

Web Profiler Config

debug can be a boolean or an object. When debug is true, the profiler is enabled. You can also configure the web profiler and exclude routes:

1
{
2
  "debug": {
3
    "enabled": true,
4
    "web-profiler": {
5
      "enabled": true,
6
      "excluded-routes": [
7
        "*._debug.*",
8
        "*.get._debug.web-profiler.*"
9
      ]
10
    }
11
  }
12
}

excluded-routes supports * wildcards and matches against the request path, route name, and a normalized key like get._debug.web-profiler.traceId.dashboard.

Package defaults are defined in @xpulse/debug/xpulse.json and can be overridden by your app xpulse.json.

Template Method

When debug is enabled, a debug(value) template method is registered (via @xpulse/template). It renders a safe HTML dump:

1
{{ debug(user) }}

debug:events:list

Lists all registered events and listeners.

debug:config:show

Shows loaded configuration from @xpulse/config.

debug:routes:list

Lists registered routes (when @xpulse/router is installed).

debug:packages:list

Lists installed @xpulse/* packages with versions.

debug:app:bootstrap

Bootstraps the app (or simulates bootstrap) and registers routes.

DataCollector API

Any @xpulse/* package can display its own data in the Web Profiler by implementing a DataCollector and placing it under src/datacollectors/. @xpulse/debug discovers these files automatically — no configuration required.

Setup

1
// src/datacollectors/my-collector.js
2
import { DataCollector } from '@xpulse/debug/collector';
3
 
4
export default class MyCollector extends DataCollector {
5
 
6
    configure() {
7
        this.setName('my-package')
8
            .setIcon('🔧')
9
            .setPackage('@xpulse/my-package');
10
    }
11
 
12
    async collect() {
13
        this.on('my:event', (payload) => {
14
            this.setBadge('active');
15
            this.addArea({
16
                title: 'Result',
17
                rows: [{ label: 'Value', value: payload.value }]
18
            });
19
        });
20
    }
21
}

@xpulse/debug must be listed in optionalDependencies:

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

configure()

Called before collect(). Sets panel metadata.

collect()

Registers event listeners via this.on(). Called once at startup.

1
this.on('my:event', (payload, traceId) => {
2
    // traceId is the active request ID
3
    // payload is the event payload
4
});

Listeners are only executed when an active traceId is present (i.e. within the context of an HTTP request). Events outside a request are ignored.

Data methods (inside listeners)

Area format

1
this.addArea({
2
    title: 'Section Title',
3
    rows: [
4
        { label: 'Key',   value: 'Value' },
5
        { label: 'Count', value: 42 },
6
    ]
7
});

SubPanel format

1
this.addSubPanel({
2
    title: 'Detail Panel',
3
    rows: [...]
4
});

Panel output

After each http:response event, the collector automatically writes:

1
var/cache/debug/_<traceId>/packages/<name>.json

This file is read by the Web Profiler and displayed as a panel tab.

appInit(options)

1
import debug from '@xpulse/debug';
2
 
3
await debug.appInit({ http: true, cli: false, debug: true });

Simulates app bootstrap based on installed packages. If @xpulse/app is installed, app.init(...) is used.