> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# Laravel Telescope – Praxistechniken
> Praxisorientierte Muster, um Telescope in der lokalen Entwicklung optimal zu nutzen. N+1-Erkennung, Tracking mit Tags, eigene Watcher, Nutzung des Dump-Watchers – Know-how, das die offizielle Dokumentation allein nicht liefert.
Installation und Grundkonfiguration finden Sie auf der [Guide-Seite](/de/telescope). 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](/de/pulse) oder [Laravel Nightwatch](/de/blog/nightwatch-introduction).
***
## 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.
```mermaid theme={null}
sequenceDiagram
participant Browser
participant Laravel
participant Telescope
participant DB
Browser->>Laravel: GET /posts
Laravel->>DB: SELECT * FROM posts (1 Query)
loop je Beitrag
Laravel->>DB: SELECT * FROM users WHERE id = ? (N Queries)
end
Laravel-->>Browser: Response
Laravel-->>Telescope: Query-Historie aufzeichnen
Note over Telescope: Gleiches SELECT N-mal
slow-Tag wird gesetzt
```
Öffnen Sie `/telescope` und identifizieren Sie im Tab „Requests" langsame Anfragen.
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.
Fügen Sie `with()` im Code hinzu und prüfen Sie die Queries erneut. Ist die Zahl deutlich gesunken, ist der Fix abgeschlossen.
```php theme={null}
// 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.
```php theme={null}
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.
```php theme={null}
// 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.
```php theme={null}
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.
```php theme={null}
// 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](https://mailpit.axllent.org/) verbessert die Mail-Entwicklung erheblich.
```ini theme={null}
# .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
```php theme={null}
// 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.
```php theme={null}
// 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.
```php theme={null}
$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 |
Details zur Installation und zu Watchern finden Sie auf der Guide-Seite.
Für Monitoring in der Produktion nutzen Sie Nightwatch.
## Related topics
- [Laravel Telescope](/de/telescope.md)
- [Laravel Pulse](/de/pulse.md)
- [Einführung in Laravel Nightwatch](/de/blog/nightwatch-introduction.md)
- [Einen MCP-Server mit Laravel bauen](/de/advanced/mcp-server.md)
- [Laravel Sentinel – Analyse der Route-Schutz-Middleware](/de/blog/sentinel-introduction.md)