Laravel Telescope hands-on techniques

Practical patterns for getting the most out of Telescope in local development. N+1 detection, tag-based tracking, custom watchers, using the Dump watcher, and know-how not covered in the official docs.

For basic installation and configuration, see the guide page. This page introduces practical local-development patterns not covered in the official docs.

Telescope is local-development only. Use Laravel Pulse or Laravel Nightwatch for production monitoring.

---

Systematically finding N+1 problems

Here’s a practical workflow for N+1 debugging with Telescope. Rather than merely noticing “the same SELECT is being repeated,” you can run through the whole cycle including post-fix verification.

1. Find slow requests in Requests

   Open /telescope and, on the Requests tab, identify long-running requests.

2. Inspect the executed SQL in Queries

   Opening the request details shows every SQL query executed during that request. If similar SELECTs repeat, that’s an N+1.

3. Fix with eager loading

   Add with() to the code and check queries again. If the query count drops significantly, you’re done.

// Code that causes N+1
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // An extra query per post
}

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

You can complete this whole workflow in the browser without adding dd() calls or extra logging to your code.

---

Tracking specific requests with tags

Telescope has a tags feature. Attaching arbitrary tags to entries with Telescope::tag() lets you quickly filter the dashboard to just entries with a tag.

This is extremely useful when you want to trace only the activity related to a specific user or order ID.

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

// Override the tags method in 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 [];
});

Now, typing user:42 in the Search box on /telescope/requests lists only requests from user 42.

Auto-tagging models

The tags method on TelescopeServiceProvider can add a specific model ID to every entry.

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

Additionally, implementing the HasTags contract on a model automatically adds tags when that model is recorded.

use Laravel\Telescope\Contracts\EntriesRepository;

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

---

Using the Dump watcher

Using dump() can inject output into HTML responses and make API debugging awkward. The Telescope Dump watcher separates dump() output from the browser response and records it in the dashboard.

Usage is simple: open the “Dump” tab in /telescope and then call dump().

// Controller
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // Appears in Telescope's dump tab
    return response()->json($users);
}

It’s captured only while the page is open, so you only monitor when you need to. Unlike dd(), it doesn’t halt execution, which is handy when debugging across a stream of consecutive requests.

---

Comfortable email debugging with Mailpit integration

Combining the Mail watcher with the local SMTP server Mailpit dramatically improves email development.

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

Telescope’s Mail tab lets you preview both HTML and text of sent emails. In Mailpit you can view received emails in the browser and also check attachments and spam scores.

To avoid accidentally sending emails externally during testing, always use a local SMTP such as Mailpit or MailHog during local development.

---

Debugging events and listeners

Debugging event-driven code is often tricky. Chasing “is the event firing?” and “which listeners run?” through logs is tedious.

Telescope’s Events watcher lists dispatched events together with their listeners.

If a listener isn’t firing, check the event entry on the Events tab.

• Event is dispatched but no listeners appear → the listener isn’t registered (check EventServiceProvider)
• The event isn’t dispatched at all → check where event() is called

// A local verification flow instead of writing a test
event(new OrderShipped($order));
// → Check that OrderShipped appears on /telescope/events
// → Check that the listener SendShippingConfirmation is invoked

---

Debugging queued jobs

Debugging async processing purely from logs makes it hard to pin down issues. Telescope’s Jobs watcher records everything from dispatch to execution result.

Clicking a failed job entry shows the stack trace and exception message. You can inspect failures in Telescope in addition to the queue:failed table, so you can identify the root cause quickly.

// While debugging jobs, running synchronously with the sync driver is easier to trace
// .env
QUEUE_CONNECTION=sync

With the sync driver, the job runs synchronously within the request, and job execution results appear in the Requests watcher too.

---

Debugging the HTTP client

When debugging communication with external APIs, the HTTP Client Watcher is useful. Requests made with the Http:: facade and their responses are recorded.

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

Response body, status code, and duration are visible at a glance. You can inspect the response in the dashboard without writing dd($response->json()).

---

Summary

Technique	Benefit
N+1 workflow	Systematically find and fix query issues without dd()
Tagging	Filter recordings for a specific user or model quickly
Dump watcher	Inspect dump output without polluting API responses
Mailpit integration	Comfortable local email development
Events watcher	Visualize event and listener firing
Jobs + sync	Debug async processing by running it synchronously
HTTP client	Record and inspect external API communication

Laravel Telescope guide

See the guide page for installation and detailed watcher settings.

Laravel Nightwatch

Monitor production with Nightwatch.