Getting Started

Install Telescope as a development dependency, publish its assets/config, and migrate its storage tables:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

On newer Laravel versions you may also use the framework installer command:

php artisan install:telescope

Open /telescope in your local environment. If the UI is not reachable, check authorization first. Telescope registers a viewTelescope gate in App\Providers\TelescopeServiceProvider; by default access is limited to the local environment. For shared staging environments, extend that gate deliberately:

protected function gate(): void
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

The first day-to-day use case is debugging a slow or failing page:

Open Requests and sort/filter by duration or response status.
Open the request entry and inspect its related Queries, Exceptions, Logs, Events, and Views.
Look for duplicate queries, missing eager loads, slow SQL, swallowed exceptions, or unexpected cache/mail/job activity.
Use the entry batch view to follow the request through anything it dispatched.

For terminal-first workflows, php artisan telescope:list exposes recorded entries and batches without opening the web UI. That is useful in agent-driven or SSH-only environments.

Implementation Patterns

Keep watchers intentional

Telescope records a lot by default. Review config/telescope.php and disable watchers you do not need, especially outside local development:

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'ignore_http_methods' => ['OPTIONS'],
        'ignore_status_codes' => [404, 419],
    ],

    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'ignore_paths' => [
            'telescope/*',
            'horizon/*',
        ],
    ],
],

This is especially important for query-heavy applications, queue workers, and any environment where Telescope is enabled temporarily.

Filter at the source

Use Telescope::filter to record only useful entries. A common pattern is to keep all exceptions/jobs but only record slow or failing HTTP requests:

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

Telescope::filter(function (IncomingEntry $entry) {
    if ($entry->isRequest()) {
        $status = $entry->content['response_status'] ?? 200;

        return $status >= 500 || ($entry->duration ?? 0) > 1000;
    }

    return true;
});

Be careful not to filter away the exception or job entries you actually need when investigating an incident.

Tag entries for correlation

Tags make it possible to connect a request, job, mail, and notification to the same user, tenant, order, or feature:

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

Telescope::tag(function (IncomingEntry $entry) {
    if ($entry->isRequest()) {
        return array_filter([
            auth()->id() ? 'user:'.auth()->id() : null,
            tenant('id') ? 'tenant:'.tenant('id') : null,
        ]);
    }

    return [];
});

Then filter by tag in the UI. Tags are attached as entries are recorded, so they are not retroactive.

Use batches as the primary debugging model

Every request, command, and job is recorded as a batch containing its queries, cache operations, logs, events, exceptions, and views. When debugging:

Start from the parent entry, not an isolated query.
Use related entries to see what happened immediately before an exception.
Compare a passing request with a failing request using their query counts and timings.
Follow queued jobs from the dispatching request into the queue worker entry.

Suppress noisy code paths

Imports, seeders, health checks, and background maintenance can flood Telescope. Wrap known-noisy code with withoutRecording:

use Laravel\Telescope\Telescope;

Telescope::withoutRecording(function () {
    $this->importLargeDataset();
});

The callback’s return value is preserved, so this can wrap service calls without changing behavior.

Production and staging usage

Telescope is primarily a local tool. If you enable it outside local:

Put it behind a strict authorization gate.
Use a separate database connection or dedicated storage database.
Disable most watchers and rely on filters.
Schedule pruning.
Avoid recording sensitive request bodies, headers, and responses.

Typical config additions:

// config/telescope.php
'connection' => env('TELESCOPE_DB_CONNECTION', 'mysql'),

// app/Console/Kernel.php or routes/console.php
$schedule->command('telescope:prune')->daily();

Set TELESCOPE_ENABLED=false by default in production and opt in only when actively debugging.

Hiding sensitive data

Configure request redaction in the request watcher config:

Watchers\RequestWatcher::class => [
    'enabled' => true,
    'hide_request_parameters' => true,
    'hide_request_headers' => true,
    'hide_response_parameters' => true,
],

Use this in any shared environment. Even locally, it prevents passwords, tokens, and personal data from being stored in Telescope’s tables.

Gotchas and Tips

Telescope is not a production monitoring system by default. Its tables can grow quickly because it stores full payloads, query bindings, headers, and stack traces. Schedule telescope:prune and consider a shorter retention window.
Authorization surprises are common. If /telescope returns 403, inspect the viewTelescope gate. The default is local-only access.
Configuration caching can mask changes. After changing TELESCOPE_ENABLED, watcher config, or filters, run php artisan config:clear if config is cached.
withoutRecording is your friend. Use it for test suites, seeders, imports, and repetitive jobs that would otherwise flood the UI. This is especially relevant for Octane and long-running workers.
Be selective with query watcher ignores. ignore_paths on the query watcher prevents noisy endpoints from recording SQL. Use it for health checks, Telescope itself, Horizon, and other internal routes.
Filtering can hide the evidence. If exceptions are not appearing, check both the exception watcher and your global Telescope::filter logic. Prefer “record all exceptions, filter noisy requests” over aggressive blanket filtering.
Tags are strings and are not retroactive. Duplicate tags are ignored. Add tags at recording time via Telescope::tag.
UI assets must be published on upgrade. After updating the package, run php artisan telescope:publish if the dashboard looks stale or broken.
Queue debugging requires a running worker. Job entries appear only when the queue worker processes them. Check the worker environment, queue connection, and failed job handling.
Use batches for root-cause analysis. A slow query by itself is less useful than seeing the request that triggered it, the job it dispatched, and the exception that followed.
Watch memory in long-running processes. Telescope has Octane-related fixes, but recording every event in a long-lived worker still costs memory. Disable unneeded watchers and use withoutRecording around high-volume loops.
Prefer the terminal when appropriate. php artisan telescope:list is useful for quick inspection, CI/debug scripts, and environments where opening the dashboard is inconvenient.
Clear vs prune. Use telescope:clear when you want a clean slate during development; use telescope:prune for scheduled retention. Clearing large datasets is chunked, but it still touches the database.
Sensitive data deserves explicit redaction. Never assume local data is harmless. Hide request parameters, headers, and response bodies anywhere real user data may flow through.

Telescope Laravel Package