Alle Artikel
Laravel4 min

Laravel Telescope einrichten – Debugging & Observability

Laravel Telescope ist eines der mächtigsten Debugging- und Monitoring-Tools im Laravel-Ökosystem. Es bietet Entwicklern tiefe Einblicke in Requests, Queries, Jobs, Exceptions und vieles mehr – alles über eine elegante Web-UI. In diesem Guide zeige ich dir, wie du Laravel Telescope einrichten kannst, welche Konfigurationen wichtig sind und worauf du in Produktionsumgebungen achten musst.

Was ist Laravel Telescope?

Laravel Telescope ist ein offizielles First-Party-Package von Laravel, das als "Debug Assistant" fungiert. Es zeichnet alle wichtigen Vorgänge deiner Anwendung auf und stellt sie übersichtlich dar:

  • HTTP-Requests und Responses
  • Datenbankabfragen mit Execution-Time
  • Jobs, Queues und Mailversand
  • Cache-Operationen
  • Redis-Commands
  • Exceptions und Logs
  • Scheduled Tasks

Im Gegensatz zu reinen Log-Files bietet Telescope eine durchsuchbare, filterbare Oberfläche, die das Debugging erheblich beschleunigt.

Laravel Telescope einrichten: Schritt-für-Schritt

1. Installation via Composer

Die Installation von Telescope erfolgt über Composer. Wichtig: Telescope sollte nur in Entwicklungs- und Staging-Umgebungen aktiv sein, nicht in Production.

composer require laravel/telescope --dev

Der --dev-Flag stellt sicher, dass Telescope nur in deiner lokalen composer.json unter require-dev landet und nicht auf Production-Servern installiert wird.

2. Telescope installieren

Nach dem Download führst du den Installationsbefehl aus:

php artisan telescope:install

Dieser Befehl erledigt mehrere Dinge:

  • Publiziert die Telescope-Config nach config/telescope.php
  • Erstellt Migrations für die Telescope-Datenbanktabellen
  • Registriert den TelescopeServiceProvider

Anschließend migrierst du die Datenbank:

php artisan migrate

Telescope erstellt mehrere Tabellen (z.B. telescope_entries, telescope_monitoring), in denen alle aufgezeichneten Daten gespeichert werden.

3. Telescope aufrufen

Nach erfolgreicher Installation kannst du Telescope über folgende URL aufrufen:

http://deine-app.test/telescope

Du siehst nun das Dashboard mit verschiedenen Tabs für Requests, Commands, Queries, Jobs usw.

Wichtige Konfigurationen

Beim Laravel Telescope einrichten solltest du einige Konfigurationsoptionen kennen. Die zentrale Config-Datei findest du unter config/telescope.php.

Umgebungsbasierte Aktivierung

Standardmäßig ist Telescope in allen Umgebungen aktiv, was ein Sicherheitsrisiko darstellt. In der TelescopeServiceProvider.php solltest du die Registrierung einschränken:

// app/Providers/TelescopeServiceProvider.php

public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

Dies stellt sicher, dass Telescope nur in deiner lokalen Entwicklungsumgebung geladen wird.

Watchers konfigurieren

Telescope nutzt sogenannte "Watchers", um verschiedene Aspekte deiner Anwendung zu überwachen. In config/telescope.php kannst du diese einzeln aktivieren oder deaktivieren:

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50, // Queries über 50ms markieren
    ],
    
    Watchers\RequestWatcher::class => [
        'enabled' => true,
        'size_limit' => 64, // KB
    ],
    
    Watchers\JobWatcher::class => true,
    
    Watchers\MailWatcher::class => true,
    
    // ...weitere Watchers
],

Der slow-Parameter beim QueryWatcher ist besonders nützlich: Du kannst langsame Queries automatisch hervorheben lassen.

Storage-Strategie anpassen

Telescope kann schnell viele Einträge sammeln. Mit der storage-Option bestimmst du, wie viele Einträge gespeichert werden:

'storage' => [
    'database' => [
        'connection' => env('DB_CONNECTION', 'mysql'),
        'chunk' => 1000,
    ],
],

Du solltest regelmäßig alte Einträge löschen. Dafür kannst du einen Scheduler-Task einrichten:

// app/Console/Kernel.php

protected function schedule(Schedule $schedule): void
{
    $schedule->command('telescope:prune --hours=48')->daily();
}

Dies löscht alle Telescope-Einträge, die älter als 48 Stunden sind.

Telescope in Staging/Production nutzen

Manchmal möchtest du Laravel Telescope einrichten auch auf Staging-Servern, um Produktionsprobleme zu debuggen. Dabei musst du besonders auf Sicherheit achten.

Zugriff über Gates beschränken

In app/Providers/TelescopeServiceProvider.php kannst du den Zugriff beschränken:

protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            'admin@example.com',
            'dev@example.com',
        ]);
    });
}

Nur Benutzer mit den angegebenen E-Mail-Adressen können Telescope dann aufrufen.

Telescope hinter HTTP-Auth schützen

Alternativ kannst du Telescope über Basic Authentication schützen. Füge in routes/web.php hinzu:

Route::middleware(['auth.basic'])->group(function () {
    Telescope::auth(function ($request) {
        return true;
    });
});

Oder nutze Middleware direkt in der Route-Registrierung.

Performance-Überlegungen

In Production solltest du bestimmte Watchers deaktivieren, die Performance-Impact haben:

// config/telescope.php für Production

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => false, // Queries nicht aufzeichnen
    ],
    
    Watchers\RequestWatcher::class => [
        'enabled' => true, // Nur kritische Watchers
    ],
],

Praktische Anwendungsfälle

1. N+1 Query-Probleme finden

Telescope zeigt dir genau, welche Queries ein Request ausgelöst hat. Über den Queries-Tab kannst du sehen, ob du versehentlich N+1-Probleme hast:

// Schlecht: N+1 Problem
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->author->name; // Separate Query für jeden Post
}

// Gut: Eager Loading
$posts = Post::with('author')->get();

Im Telescope-Dashboard siehst du sofort die Anzahl der Queries und kannst optimieren.

2. Job-Failures debuggen

Wenn Queue-Jobs fehlschlagen, zeigt dir Telescope den vollständigen Stack-Trace im Jobs-Tab. Du siehst:

  • Welche Payload übergeben wurde
  • Welcher Fehler aufgetreten ist
  • Wie lange der Job lief

3. Mail-Versand testen

Im Mail-Tab kannst du alle verschickten E-Mails einsehen – inklusive HTML-Preview. Perfekt für lokales Testing ohne echten Mail-Versand.

Fazit: Laravel Telescope einrichten für besseres Debugging

Laravel Telescope einrichten ist in wenigen Minuten erledigt und bietet enormen Mehrwert beim Entwickeln und Debuggen von Laravel-Anwendungen. Die wichtigsten Takeaways:

  • Installation nur als --dev-Dependency
  • Zugriff auf Production-Umgebungen über Gates absichern
  • Regelmäßig alte Einträge mit telescope:prune löschen
  • Watchers selektiv aktivieren, um Performance zu optimieren

Mit Telescope bekommst du X-Ray-Vision für deine Laravel-App und kannst Probleme identifizieren, bevor sie zu echten Issues werden.

Du arbeitest an einem Laravel-Projekt und brauchst Unterstützung beim Debugging oder Performance-Optimierung? Ich helfe dir gerne – von der Telescope-Konfiguration bis zur Anwendungsarchitektur.

Laravel Telescope einrichtenLaravelFreelancerWebentwicklungDüsseldorf
Anfrage senden