Techniques pratiques de Laravel Telescope

Patrons pratiques pour tirer le meilleur parti de Telescope en développement local : détection N+1, suivi par tags, watchers personnalisés, watcher Dump, etc. — un condensé de savoir-faire absent de la documentation officielle.

Pour l’installation et la configuration de base, reportez-vous à la page de guide. Cette page présente des patrons pratiques pour le développement local qui ne figurent pas dans la documentation officielle.

Telescope est un outil réservé au développement local. Pour la supervision de la production, utilisez Laravel Pulse ou Laravel Nightwatch.

---

​

Détecter les problèmes N+1 méthodiquement

Voici un flux pratique de debug N+1 avec Telescope. Il ne s’agit pas seulement de « remarquer que le même SELECT se répète » mais de mener toute la démarche, jusqu’à la vérification après correction.

1. Repérer les requêtes lentes dans Requests

   Ouvrez /telescope, onglet Requests, identifiez les requêtes à temps d’exécution élevé.

2. Vérifier les SQL dans Queries

   Le détail d’une requête liste toutes les SQL exécutées pendant la requête. Si un même SELECT se répète, c’est un N+1.

3. Corriger avec de l'eager loading

   Ajoutez with() et rechargez. Si le nombre de requêtes chute nettement, la correction est bonne.

// Code qui provoque un N+1
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // Une requête par article
}

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

Toute la démarche se fait dans le navigateur, sans ajouter de dd() ni de logs.

---

​

Suivi de requêtes précises via les tags

Telescope possède une fonctionnalité de tags. Telescope::tag() ajoute des tags arbitraires à une entrée, ce qui permet de filtrer rapidement le dashboard.

Très utile pour suivre les traitements liés à un utilisateur donné ou une commande précise.

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

// Redéfinir la méthode tags 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 [];
});

Sur /telescope/requests, taper user:42 dans la recherche liste immédiatement toutes les requêtes de l’utilisateur 42.

​

Tags automatiques sur les modèles

Dans la méthode tags du TelescopeServiceProvider, vous pouvez appliquer l’ID d’un modèle à toutes les entrées.

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

En implémentant le contract HasTags sur le modèle, ses tags sont ajoutés automatiquement lorsqu’il est enregistré.

use Laravel\Telescope\Contracts\EntriesRepository;

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

---

​

Utiliser le watcher Dump

Utiliser dump() peut polluer la réponse HTML et compliquer le debug d’une API. Le watcher Dump de Telescope permet de dévier la sortie de dump() vers le dashboard plutôt que la réponse.

L’utilisation est simple : ouvrez l’onglet « Dump » de /telescope et appelez dump().

// Contrôleur
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // S'affiche dans l'onglet dump de Telescope
    return response()->json($users);
}

La capture n’a lieu que lorsque la page est ouverte, vous ne surveillez que ce dont vous avez besoin. Contrairement à dd(), l’application n’est pas interrompue : pratique pour enchaîner des requêtes.

---

​

Debug e-mail confortable avec Mailpit

Combiner le watcher Mail avec le serveur SMTP local Mailpit transforme le développement d’e-mails.

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

L’onglet Mail de Telescope prévisualise HTML et texte des e-mails envoyés. Mailpit permet de voir les e-mails reçus dans le navigateur, avec vérification des pièces jointes et du score anti-spam.

Pour éviter d’envoyer accidentellement des e-mails en externe, utilisez toujours Mailpit ou Mailhog en local.

---

​

Debug d’événements et de listeners

L’event-driven est souvent difficile à déboguer. « L’événement est-il déclenché ? », « Quels listeners sont appelés ? » — suivre cela dans les logs est fastidieux.

Le watcher Events de Telescope liste les événements dispatchés et leurs listeners.

Si un listener n’est pas appelé, ouvrez son entrée dans l’onglet Events.

• L’événement est bien dispatché mais aucun listener n’apparaît → listener non enregistré (vérifiez EventServiceProvider)
• L’événement n’est même pas dispatché → vérifiez l’appel à event()

// À exécuter en local à la place d'un test
event(new OrderShipped($order));
// → Vérifier dans /telescope/events que OrderShipped apparaît
// → Vérifier que le listener SendShippingConfirmation est appelé

---

​

Debug de jobs de queue

Déboguer de l’asynchrone à partir des logs seuls est difficile. Le watcher Jobs de Telescope trace du dispatch à l’exécution.

Sur un job en échec, cliquez pour voir la stack trace et le message d’exception. Complémentaire à la table queue:failed, il accélère l’analyse des échecs.

// Pour déboguer, le driver sync facilite le suivi (exécution synchrone)
// .env
QUEUE_CONNECTION=sync

Avec le driver sync, le job s’exécute dans la requête et son résultat est inclus dans le watcher Requests.

---

​

Debug du client HTTP

Pour tracer les échanges avec des API externes, le watcher HTTP Client est très utile. Les requêtes faites via la facade Http:: et leurs réponses sont enregistrées.

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

Le contenu de la réponse, le code de statut et le temps d’exécution s’affichent en un coup d’œil. Plus besoin d’écrire dd($response->json()).

---

​

Conclusion

Technique	Bénéfice
Workflow N+1	Trouver et corriger les problèmes de requêtes sans dd()
Tags	Filtrer immédiatement les entrées d’un utilisateur/objet
Watcher Dump	Voir la sortie de dump() sans altérer la réponse API
Mailpit	Confort de développement e-mail local
Watcher Events	Visualiser le déclenchement des événements et listeners
Jobs + sync	Déboguer les asynchrones en synchrone
Client HTTP	Trace et vérification des appels API externes

Guide Laravel Telescope

Consultez la page guide pour l’installation et la configuration des watchers.

Laravel Nightwatch

Pour la supervision en production, utilisez Nightwatch.