19: Trace

Phlo's trace mode is een runtime-instrumentatielaag die elke aanroep naar een gegenereerde method, prop getter, static of native functie logt met timing en argumenten. Per verzoek schrijft Phlo een JSON-dump naar data/trace/<id>.json. Bedoeld voor debugging en profiling, niet voor productie.

19.1: Wat trace doet

Met trace ingeschakeld, voegt de transpiler van Phlo één regel toe aan de bovenkant van elke gegenereerde method:

trace('class->method', compact('arg1', 'arg2'))

En Phlo laadt functions.trace.php (een gegenereerde variant van functions.php) zodat native helpers, esc(), arr(), loop(), view(), apply(), alles, ook een trace-aanroep krijgen. Het resultaat: een complete chronologische log van wat er gebeurde tijdens een verzoek.

19.2: Inschakelen

In je dev entrypoint:

phlo_app (
	id:    'Example',
	host:  'dev.example.nl',
	build: true,
	debug: true,
	trace: true,
)

De volgende build (elke ontwikkelaarsverzoek, of build::run) injecteert de trace() aanroepen; vanaf dat moment wordt elke aanroep gelogd.

Trace-uitvoer gaat naar data/trace/. De map wordt automatisch aangemaakt.

19.3: Wat een trace bevat

Eén JSON-bestand per verzoek met:

Elke gebeurtenis in events:

{
	"t":    12.345,
	"k":    "call",
	"c":    "user",
	"n":    "byEmail",
	"node": "user->byEmail",
	"f":    "user.phlo",
	"args": {"email": "jordi@example.nl"}
}

19.4: Argument snipping

Volledige argumentwaarden zouden de trace onleesbaar maken. Phlo snijdt:

Dat is genoeg om te zien welke records zijn aangeraakt zonder de volledige payload te dumpen.

19.5: Lezen via het Phlo Control Center

Het Phlo Control Center heeft een Trace tabblad dat data/trace/index.json leest. De meest recente trace staat bovenaan; een selectievak opent oudere. Per trace zie je active, sequence en de evenementstroom.

index.json houdt de laatste 100 traces bij. Oudere worden automatisch verwijderd samen met hun JSON-bestand.

19.6: Onderhoud: `build::traceShadow`

functions.trace.php is een gegenereerd bestand. Telkens wanneer je iets toevoegt of iets wijzigt in functions.php, genereer het opnieuw:

php www/app.php build::traceShadow

Dit parseert functions.php en injecteert, in elke function foo($a, $b), als de eerste verklaring:

trace('foo', compact('a', 'b'))

Dan align je de inhoud van functions.trace.php met de bron. De opdracht is alleen relevant voor degenen die aan de Phlo-runtime zelf werken, niet voor app-code.

19.7: Wanneer het te gebruiken, wanneer niet

Do:

• Een verzoek is traag "ergens" en je wilt weten waar de tijd naartoe gaat
• Verkennen van een onbekende app: sequence toont je het werkelijke pad door de code
• Foutopsporing van een raceconditie of bijeffect: events toont de exacte volgorde + timing
• Voor onderwijs: laten zien hoe een Phlo-verzoek zich daadwerkelijk ontvouwt

Don't:

• Productie, elke methode-aanroep kost een logvermelding en een schijfschrijfactie per verzoek
• thread: true workers, trace schrijft per verzoek en is daarom, net als build, niet worker-veilig
• Prestatiemeting tot op de microseconde, de instrumentatie zelf voegt overhead toe

Zet trace: true aan wanneer je het nodig hebt; zet het uit wanneer je klaar bent. Het Control Center blijft de historische traces tonen totdat de auto-prune ze opruimt.