Laravel Telescope – Praxistechniken

Installation und Grundkonfiguration finden Sie auf der Guide-Seite. Auf dieser Seite geht es um praxisnahe Nutzungsmuster in der lokalen Entwicklung, die die offizielle Dokumentation nicht abdeckt. Telescope ist ein Werkzeug ausschließlich für die lokale Entwicklung. Für Monitoring in der Produktion verwenden Sie Laravel Pulse oder Laravel Nightwatch.

N+1-Probleme systematisch aufspüren

Ein praxisnaher Ablauf, um N+1-Fehler mit Telescope zu debuggen. Nicht nur zu bemerken, „dass sich SELECTs wiederholen”, sondern der komplette Workflow bis zur Verifikation.

Langsame Requests im Tab 'Requests' finden

Öffnen Sie /telescope und identifizieren Sie im Tab „Requests” langsame Anfragen.

Ausgeführtes SQL unter 'Queries' prüfen

In der Request-Detailansicht sehen Sie alle während der Anfrage ausgeführten SQL-Queries. Wiederholt sich ein SELECT wieder und wieder, handelt es sich um N+1.

Eager Loading ergänzen und beheben

Fügen Sie with() im Code hinzu und prüfen Sie die Queries erneut. Ist die Zahl deutlich gesunken, ist der Fix abgeschlossen.

// Code, der N+1 auslöst
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // pro Beitrag eine weitere Query
}

// Fix per Eager Loading
$posts = Post::with('user')->get();

Sie führen den gesamten Ablauf im Browser durch, ohne dd() oder Logs in den Code einzubauen.

Bestimmte Requests per Tags nachverfolgen

Telescope bietet eine Tag-Funktion. Mit Telescope::tag() weisen Sie einem Eintrag beliebige Tags zu und filtern das Dashboard schnell nach diesen Tags. Besonders nützlich, um Vorgänge zu einer bestimmten Nutzer- oder Bestell-ID zu verfolgen.

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

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

    return [];
});

Geben Sie in /telescope/requests in der Suche user:42 ein, listet Telescope nur die Requests des Nutzers mit ID 42 auf.

Modelle automatisch taggen

Mit der Methode tags im TelescopeServiceProvider können Sie bestimmte Modell-IDs an alle Einträge anhängen.

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

Implementieren Sie zusätzlich den Contract HasTags an Ihrem Modell, damit das Modell beim Aufzeichnen automatisch getaggt wird.

use Laravel\Telescope\Contracts\EntriesRepository;

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

Nutzung des Dump-Watchers

Wenn Sie dump() verwenden, mischt sich die Ausgabe in HTML-Responses und erschwert das Debugging von APIs. Der Dump-Watcher von Telescope schreibt die Ausgabe von dump() in das Dashboard, statt sie in die Browser-Response zu senden. Die Verwendung ist einfach: Öffnen Sie in /telescope den Tab „Dump” und rufen Sie dump() auf.

// Controller
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // erscheint im Dump-Tab von Telescope
    return response()->json($users);
}

Die Erfassung erfolgt nur, solange die Seite geöffnet ist – Sie beobachten also gezielt. Anders als dd() stoppt die Ausführung nicht, sodass Sie fortlaufend Requests durchreichen können.

E-Mail-Debugging komfortabel mit Mailpit

Die Kombination aus Mail-Watcher und dem lokalen SMTP-Server Mailpit verbessert die Mail-Entwicklung erheblich.

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

Im Mail-Tab von Telescope können Sie ausgehende Mails in HTML und Text prüfen. In Mailpit sehen Sie empfangene Mails im Browser, inklusive Anhängen und Spam-Score.

Damit Sie versehentlich keine Mails an externe Empfänger senden, verwenden Sie lokal stets ein lokales SMTP wie Mailpit oder Mailhog.

Debugging von Events und Listenern

Das Debuggen von Event-getriebenem Code ist oft schwierig. „Wird das Event überhaupt gefeuert?” oder „Welche Listener werden aufgerufen?” – im Log nachzuverfolgen ist mühsam. Der Events-Watcher von Telescope listet die gefeuerten Events und die zugehörigen Listener auf. Wird ein Listener nicht aufgerufen, prüfen Sie im Tab „Events” den Eintrag:

Event wird gefeuert, aber kein Listener erscheint → Listener nicht registriert (EventServiceProvider prüfen)
Event selbst wird nicht gefeuert → die event()-Aufrufstelle prüfen

// Statt eines Tests lokal ausprobieren
event(new OrderShipped($order));
// → in /telescope/events prüfen, ob OrderShipped erscheint
// → prüfen, ob der Listener SendShippingConfirmation aufgerufen wird

Queue-Jobs debuggen

Bei asynchroner Verarbeitung ist die Ursachenermittlung über Logs schwierig. Der Jobs-Watcher von Telescope zeichnet den Dispatch bis zum Ergebnis auf. Ein Klick auf einen fehlgeschlagenen Eintrag zeigt Stacktrace und Exception. Die Diagnose gelingt schneller als über die Tabelle queue:failed allein.

// Beim Debuggen von Jobs erleichtert der sync-Treiber das Nachverfolgen
// .env
QUEUE_CONNECTION=sync

Der sync-Treiber führt Jobs synchron innerhalb der Anfrage aus; die Ausführung erscheint dadurch auch im Requests-Watcher.

HTTP-Client debuggen

Beim Debuggen externer API-Kommunikation hilft der HTTP-Client-Watcher. Anfragen über die Http::-Facade und die zugehörigen Antworten werden aufgezeichnet.

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

Response-Inhalt, Statuscode und Laufzeit sind auf einen Blick sichtbar. dd($response->json()) ist überflüssig – das Dashboard genügt.

Fazit

Technik	Nutzen
N+1-Workflow	Query-Probleme systematisch ohne `dd()` finden und beheben
Tagging	Einträge bestimmter Nutzer/Modelle sofort filtern
Dump-Watcher	Dump-Ausgaben prüfen, ohne API-Responses zu verunreinigen
Mailpit-Integration	Angenehme lokale E-Mail-Entwicklung
Events-Watcher	Event- und Listener-Feuerung visuell prüfen
Jobs + sync	Asynchrone Verarbeitung synchron debuggen
HTTP-Client	Aufzeichnen und Prüfen externer API-Aufrufe

Laravel-Telescope-Leitfaden

Details zur Installation und zu Watchern finden Sie auf der Guide-Seite.

Laravel Nightwatch

Für Monitoring in der Produktion nutzen Sie Nightwatch.

​N+1-Probleme systematisch aufspüren

​Bestimmte Requests per Tags nachverfolgen

​Modelle automatisch taggen

​Nutzung des Dump-Watchers

​E-Mail-Debugging komfortabel mit Mailpit

​Debugging von Events und Listenern

​Queue-Jobs debuggen

​HTTP-Client debuggen

​Fazit

Laravel-Telescope-Leitfaden

Laravel Nightwatch

N+1-Probleme systematisch aufspüren

Bestimmte Requests per Tags nachverfolgen

Modelle automatisch taggen

Nutzung des Dump-Watchers

E-Mail-Debugging komfortabel mit Mailpit

Debugging von Events und Listenern

Queue-Jobs debuggen

HTTP-Client debuggen

Fazit