Praktische technieken voor Laravel Telescope

Raadpleeg voor de basisinstallatie en -configuratie de gidspagina. Op deze pagina bespreken we praktische gebruikspatronen voor lokale ontwikkeling die niet in de officiële documentatie staan. Telescope is een tool uitsluitend voor lokale ontwikkeling. Gebruik voor monitoring in productie Laravel Pulse of Laravel Nightwatch.

N+1-problemen systematisch opsporen

We lopen de praktische flow van N+1-debugging met Telescope door. Je merkt niet alleen op dat “dezelfde SELECT wordt herhaald”, maar voert de hele workflow uit, inclusief de controle na de fix.

Vind trage requests via Requests

Open /telescope en identificeer op het tabblad Requests de requests met een lange uitvoeringstijd.

Controleer de uitgevoerde SQL via Queries

Open je de details van een request, dan zie je alle SQL-queries die tijdens die request zijn uitgevoerd. Wordt eenzelfde soort SELECT herhaald, dan heb je een N+1.

Los het op met eager loading

Voeg with() toe aan je code en controleer de queries opnieuw. Is het aantal queries flink gedaald, dan is de fix geslaagd.

// Code die een N+1 veroorzaakt
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // Een extra query per post
}

// Opgelost met eager loading
$posts = Post::with('user')->get();

Je doorloopt deze hele flow in de browser, zonder dd() of logregels aan je code toe te voegen.

Specifieke requests volgen met tags

Telescope heeft een tags-functie. Geef je met Telescope::tag() een willekeurige tag aan entries, dan kun je in het dashboardfilter snel alleen de entries met die tag tonen. Dit is bijzonder handig wanneer je alleen de verwerking rond een specifieke gebruikers-ID of order-ID wilt volgen.

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

// Override de tags-methode van de TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
    if ($entry->type === 'request') {
        return array_filter([
            'status:' . $entry->content['response_status'],
            auth()->check() ? 'user:' . auth()->id() : null,
        ]);
    }

    return [];
});

Typ nu in het zoekveld van /telescope/requests simpelweg user:42 en je ziet alleen de requests van gebruiker met ID 42.

Tags automatisch toekennen aan modellen

Via de tags-methode van de TelescopeServiceProvider kun je een specifieke model-ID aan alle entries toevoegen.

// TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
    return $entry->tags();
});

Implementeer je bovendien het contract HasTags op een model, dan wordt de tag automatisch toegevoegd wanneer dat model wordt vastgelegd.

use Laravel\Telescope\Contracts\EntriesRepository;

class Order extends Model implements \Laravel\Telescope\Contracts\HasTags
{
    public function telescopeTags(): array
    {
        return ['order:' . $this->id];
    }
}

De Dump-watcher benutten

Gebruik je dump(), dan komt de output in de HTML-response terecht en wordt het debuggen van API’s lastig. Met de Dump-watcher van Telescope kun je de output van dump() loskoppelen van de browserresponse en vastleggen in het dashboard. Het gebruik is eenvoudig: roep dump() aan terwijl het tabblad “Dump” van /telescope openstaat.

// Controller
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // Verschijnt op het dump-tabblad van Telescope
    return response()->json($users);
}

De output wordt alleen vastgelegd terwijl de pagina openstaat, zodat je alleen monitort wanneer dat nodig is. Anders dan dd() stopt het de uitvoering van je app niet, wat handig is bij het debuggen terwijl je een reeks requests afvuurt.

Comfortabel e-mails debuggen met Mailpit

Door de Mail-watcher te combineren met de lokale SMTP-server Mailpit verbetert de flow van e-mailontwikkeling aanzienlijk.

# .env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

Op het Mail-tabblad van Telescope kun je zowel de HTML- als de tekstversie van verzonden e-mails previewen. In Mailpit bekijk je ontvangen e-mails in de browser, inclusief bijlagen en zelfs de spamscore.

Gebruik lokaal altijd een lokale SMTP-server zoals Mailpit of Mailhog, zodat je tijdens het testen niet per ongeluk e-mails naar buiten stuurt.

Events en listeners debuggen

Het debuggen van een event-driven implementatie is vaak lastig. “Wordt het event wel afgevuurd?” en “Welke listener wordt aangeroepen?” via logs uitzoeken is omslachtig. Met de Events-watcher van Telescope zie je in één overzicht welke events zijn afgevuurd en welke listeners daarbij horen. Wordt een listener niet aangeroepen, controleer dan de entry van het event op het tabblad Events.

Het event wordt afgevuurd maar er verschijnt geen listener → de listener is niet geregistreerd (controleer de EventServiceProvider)
Het event zelf wordt niet afgevuurd → controleer de plek waar event() wordt aangeroepen

// Lokaal controleren in plaats van via een test
event(new OrderShipped($order));
// → Controleer in /telescope/events of OrderShipped verschijnt
// → Controleer of de listener SendShippingConfirmation is aangeroepen

Queue-jobs debuggen

Bij het debuggen van asynchrone verwerking is de oorzaak lastig te achterhalen door alleen naar logs te kijken. De Jobs-watcher van Telescope legt alles vast, van het dispatchen van de job tot het uitvoeringsresultaat. Klik je op de entry van een mislukte job, dan zie je de stacktrace en de exceptiemelding. Naast de queue:failed-tabel kun je het ook in Telescope bekijken, waardoor het onderzoeken van de faaloorzaak snel gaat.

// Bij het debuggen van jobs is synchroon uitvoeren met de sync-driver makkelijker te volgen
// .env
QUEUE_CONNECTION=sync

Met de sync-driver wordt de job synchroon binnen de request uitgevoerd en bevat de Requests-watcher ook het uitvoeringsresultaat van de job.

De HTTP-client debuggen

Bij het debuggen van communicatie met externe API’s helpt de HTTP Client Watcher. Requests via de Http::-facade en de bijbehorende responses worden vastgelegd.

$response = Http::get('https://api.example.com/users');
// → Te bekijken in /telescope/client-requests

Je ziet in één oogopslag de inhoud van de response, de statuscode en de uitvoeringstijd. Je hoeft geen dd($response->json()) te schrijven: alles staat in het dashboard.

Samenvatting

Techniek	Effect
N+1-workflow	Queryproblemen systematisch vinden en oplossen zonder dd()
Taggen	Records van specifieke gebruikers/modellen direct filteren
Dump-watcher	Dump-output bekijken zonder de API-response te vervuilen
Mailpit-integratie	Comfortabele lokale e-mailontwikkeling
Events-watcher	Het afvuren van events/listeners visueel controleren
Jobs + sync	Asynchrone verwerking synchroon uitvoeren en debuggen
HTTP-client	Communicatie met externe API’s vastleggen en controleren

Laravel Telescope-gids

Raadpleeg de gidspagina voor details over installatie en watcher-configuratie.

Laravel Nightwatch

Monitoring in productie doe je met Nightwatch.

Changelog

Laravel 13

Producten

Package-introducties

Nieuwe repositories verkennen

Upgradegidsen

Authenticatie

Frontend

Omgeving opzetten

Praktische technieken voor Laravel Telescope

N+1-problemen systematisch opsporen

Specifieke requests volgen met tags

Tags automatisch toekennen aan modellen

De Dump-watcher benutten

Comfortabel e-mails debuggen met Mailpit

Events en listeners debuggen

Queue-jobs debuggen

De HTTP-client debuggen

Samenvatting

Laravel Telescope-gids

Laravel Nightwatch

​N+1-problemen systematisch opsporen

​Specifieke requests volgen met tags

​Tags automatisch toekennen aan modellen

​De Dump-watcher benutten

​Comfortabel e-mails debuggen met Mailpit

​Events en listeners debuggen

​Queue-jobs debuggen

​De HTTP-client debuggen

​Samenvatting

Laravel Telescope-gids

Laravel Nightwatch

N+1-problemen systematisch opsporen

Specifieke requests volgen met tags

Tags automatisch toekennen aan modellen

De Dump-watcher benutten

Comfortabel e-mails debuggen met Mailpit

Events en listeners debuggen

Queue-jobs debuggen

De HTTP-client debuggen

Samenvatting