Debugging

Finch heeft een ingebouwde debugger die gedetailleerde foutpagina's weergeeft in de ontwikkelomgeving.

Debugger inschakelen

Twee instellingen zijn vereist:

// In lib/app.dart
FinchConfigs(
  enableLocalDebugger: true,   // Instelling 1: debugger inschakelen
)

// In bin/finch.dart
FinchApp.run(
  app: App(),
  isLocalDebug: true,          // Instelling 2: uitvoeren in lokale debugmodus
)

Beide instellingen moeten true zijn om foutpagina's voor debugging weer te geven.

Hoe `isLocalDebug` wordt berekend

Doorgaans wordt isLocalDebug gelezen uit een omgevingsvariabele:

FinchApp.run(
  app: App(),
  isLocalDebug: env.get('APP_ENV') == 'local',
)

Op die manier kun je de debugger uitschakelen door APP_ENV=production in te stellen bij deployment.

Sjabloonvariabele

In Jinja-sjablonen is isLocalDebug beschikbaar:

{% if isLocalDebug %}
  <div class="debug-bar">
    Omgeving: Ontwikkeling | Versie: {{ appVersion }}
  </div>
{% endif %}

Terminalpaneel

Wanneer de app wordt gestart met finch serve (niet met een gewone dart run), opent de CLI een WebSocket-server op --terminalPort (standaard 8282) die de stdout/stderr van het draaiende proces streamt. Het tabblad Terminal van de debugbalk maakt automatisch verbinding met deze poort, zodat je serverlogs en console-uitvoer kunt bekijken zonder naar het terminalvenster te wisselen, en vanuit de browser opdrachten terug kunt sturen naar het draaiende proces.

# Aangepaste terminalpoort gebruiken
finch serve --terminalPort 9000

Dit werkt alleen via finch serve, aangezien dat het proces is dat de app opstart en FINCH_TERMINAL_PORT in de omgeving ervan zet. Als je de app rechtstreeks met dart run uitvoert, blijft het tabblad Terminal niet verbonden.

DartDevTools-paneel

finch serve start de app ook met --enable-vm-service=8181/0.0.0.0 --disable-service-auth-codes, waardoor de Dart VM-service aan alle interfaces wordt gebonden (niet alleen localhost), zodat deze ook vanuit een Docker-container bereikbaar blijft. De debugbalk bevat een tabblad DevTools dat verbinding maakt met deze VM-service op poort 8181, en biedt zo geheugen-, prestatie- en logweergaven van de draaiende app rechtstreeks in de browser.

Als je Finch in Docker draait, zorg er dan voor dat de poorten 8181 en 8282 samen met de app-poort worden gepubliceerd — zie Docker for Finch.

Foutpagina's

Wanneer de debugger is ingeschakeld:

Onverwerkte fouten tonen een volledige stacktrace in de browser
404- en 500-fouten tonen informatieve, overzichtelijke pagina's
Verzoekgegevens (headers, params, body) zijn zichtbaar

In productiemodus (isLocalDebug: false):

Generieke foutpagina's worden aan gebruikers getoond
Stacktraces worden gelogd op de console, niet in de browser

Op deze pagina