17. Trace - Phlo

17: 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.

17.1: Welke trace doet

Met trace ingeschakeld, injecteert de compiler van Phlo één regel 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 tijdens een verzoek is gebeurd.

17.2: Inschakelen

In uw ontwikkelingsinstap:

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

Voer vervolgens build::run uit zodat de gegenereerde PHP de trace() injecties bevat. Vanaf het volgende verzoek wordt elke oproep gelogd.

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

17.3: Wat een trace bevat

Eén JSON-bestand per verzoek met:

Veld	Inhoud
`id`	Datum-tijd + willekeurige suffix, ook de bestandsnaam
`path`, `method`, `route`	Verzoekcontext
`ts`, `ms`, `count`	Starttimestamp, totale duur, aantal gebeurtenissen
`active`	Kaart per bestand → soort → aanroepcount (snelle overzicht van "wat vaak is aangeraakt")
`sequence`	Volgorde van eerste aanraking per bestand (visualiseert het verzoekpad door je app)
`events`	Volledige log: zie hieronder

Elke gebeurtenis in events:

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

Veld	Betekenis
`t`	Offset in ms sinds de start van het verzoek
`k`	Soort: `call`, `static`, `get` (prop get), `set` (prop set), `function`
`c`, `n`	Klasse en naam
`f`	Bronbestand (opgelost via classmap + sourcemap)
`args`	Afgebroken argumenten, zie X.4

17.4: Argument snipping

Volledige argumentwaarden zouden de trace onleesbaar maken. Phlo snijdt:

Type	Wordt
`null`, `bool`, `int`, `float`	onveranderd
`string` > 200 tekens	`...` afgekapt op 200
`array`	`'[N items]'` (alleen lengte)
`object` met een `id` eigenschap	`{class: ..., id: ...}`
Andere `object`	`{class: ...}`

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

17.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.

17.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'))

Vervolgens 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.

17.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.