API

Trace ID Workflow

@xpulse/http erzeugt pro Request eine traceId.
traceId wird an req.traceId angehaengt und in http:* Events emittiert.
@xpulse/controller gibt sie als _traceId an Templates weiter.
@xpulse/template traegt traceId in Render-Events.
@xpulse/debug sammelt alles pro Trace und speichert unter var/cache/debug/_<traceId>/.

Web Profiler Konfiguration

debug kann ein Boolean oder ein Objekt sein. Wenn debug true ist, ist der Profiler aktiv. Zusätzlich kann der Web Profiler konfiguriert werden und Routen können ausgeschlossen werden:

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 unterstützt * Wildcards und matched gegen Request-Path, Route-Name und einen normalisierten Key wie get._debug.web-profiler.traceId.dashboard.

Package-Defaults sind in @xpulse/debug/xpulse.json definiert und koennen durch die App-xpulse.json ueberschrieben werden.

Template-Methode

Wenn debug aktiv ist, wird die Template-Methode debug(value) registriert (via @xpulse/template). Sie rendert einen sicheren HTML-Dump:

1 {{ debug(user) }}

debug:events:list

Listet alle registrierten Events und Listener.

debug:config:show

Zeigt die geladene Konfiguration aus @xpulse/config.

debug:routes:list

Listet alle registrierten Routen (wenn @xpulse/router installiert ist).

debug:packages:list

Listet alle installierten @xpulse/* Packages mit Version.

debug:app:bootstrap

Bootstrapped die App (oder simuliert den Bootstrap) und registriert Routes.

DataCollector API

Jedes @xpulse/* Package kann eigene Daten im Web Profiler anzeigen, indem es einen DataCollector implementiert und unter src/datacollectors/ ablegt. @xpulse/debug discovert diese Dateien automatisch — keine Konfiguration nötig.

Einrichten

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

@xpulse/debug muss in optionalDependencies eingetragen sein:

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

configure()

Wird vor collect() aufgerufen. Setzt Metadaten des Panels.

Methode	Beschreibung
`this.setName(name)`	Panel-ID und Dateiname (`name.json`)
`this.setIcon(icon)`	Emoji oder Icon-String für die Toolbar
`this.setPackage(pkg)`	Package-Name für die Panel-Anzeige

collect()

Registriert Event-Listener via this.on(). Die Methode wird einmal beim Startup aufgerufen.

1 this.on('mein:event', (payload, traceId) => {
2     // traceId ist die aktive Request-ID
3     // payload ist das Event-Payload
4 });

Listener werden nur ausgeführt wenn eine aktive traceId vorhanden ist (d.h. im Kontext eines HTTP-Requests). Events außerhalb eines Requests werden ignoriert.

Daten-Methoden (innerhalb von Listenern)

Methode	Beschreibung
`this.setBadge(text)`	Badge-Text in der Debug-Toolbar
`this.addArea(area)`	Sektion im Panel hinzufügen
`this.addSubPanel(panel)`	Unter-Panel hinzufügen
`this.addSpan(span)`	Waterfall-Span zur zentralen Zeitleiste hinzufügen
`this.addTraceEvent(evt)`	Event-Eintrag zur Zeitleiste hinzufügen

Area-Format

1 this.addArea({
2     title: 'Abschnitt-Titel',
3     rows: [
4         { label: 'Schlüssel', value: 'Wert' },
5         { label: 'Anzahl',    value: 42 },
6     ]
7 });

SubPanel-Format

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

Panel-Output

Nach jedem http:response Event schreibt der Collector automatisch:

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

Diese Datei wird vom Web Profiler eingelesen und als Panel-Tab dargestellt.

appInit(options)

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

Simuliert den App-Bootstrap basierend auf vorhandenen Packages. Wenn @xpulse/app installiert ist, wird app.init(...) genutzt.

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	}

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

1	this.on('mein:event', (payload, traceId) => {
2	// traceId ist die aktive Request-ID
3	// payload ist das Event-Payload
4	});

1	this.addArea({
2	title: 'Abschnitt-Titel',
3	rows: [
4	{ label: 'Schlüssel', value: 'Wert' },
5	{ label: 'Anzahl', value: 42 },
6	]
7	});

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