Telescope Laravel Package

Getting Started

Install Telescope via Composer:

composer require laravel/telescope --dev

Publish Telescope’s assets and configuration:

php artisan telescope:install

Run the migration to create the necessary database tables:

php artisan migrate

Start Telescope in your local environment by adding it to routes/web.php:

Route::middleware(['web', 'telescope.screenshots', 'telescope'])
     ->group(function () {
         \Laravel\Telescope\Telescope::routes();
     });

Access Telescope at /telescope (protected by auth:sanctum by default). For quick debugging, use the telescope:clear command to reset entries.

First Use Case: Debug a failing request by inspecting its HTTP details, exceptions, and database queries in Telescope’s dashboard.

Implementation Patterns

Core Workflows

1. Request Debugging

   • Use Telescope’s Requests tab to inspect incoming HTTP requests, including headers, payloads, and responses.
   • Filter by tags (e.g., api, admin) or time ranges for targeted debugging.
   • Example: Add a tag to a request in middleware:

     public function handle($request, Closure $next) {
         $request->telescopeData['tags'] = ['api', 'v1'];
         return $next($request);
     }
     

2. Exception Tracking

   • View exceptions in the Exceptions tab, including stack traces and context.
   • Reproduce issues by clicking "Replay" to simulate the request.

3. Database Query Analysis

   • Analyze slow queries in the Queries tab, with execution time and SQL formatting.
   • Use the DB::enableQueryLog() pattern to manually log queries:

     DB::enableQueryLog();
     // ... code ...
     Telescope::logQuery(DB::getQueryLog());
     

4. Job Monitoring

   • Track queued jobs in the Jobs tab, including payloads and exceptions.
   • Filter by job class or queue name (e.g., default, high).

5. Custom Data Logging

   • Log custom events (e.g., business logic) using Telescope::log():

     Telescope::log('Custom Event', [
         'user_id' => auth()->id(),
         'action' => 'purchase',
     ]);
     

Integration Tips

• Middleware: Use TelescopeMiddleware to automatically tag requests:

  public function handle($request, Closure $next) {
      $request->telescopeData['tags'] = ['authenticated'];
      return $next($request);
  }
  

• Service Providers: Register custom watchers (e.g., for third-party services):

  public function boot() {
      Telescope::make()->extend(function ($telescope) {
          $telescope->watch(\App\Services\StripeService::class);
      });
  }
  

• Environment-Specific: Disable Telescope in production by setting TELESCOPE_ENABLED=false in .env.

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Telescope logs all requests, queries, and jobs by default. For high-traffic apps, limit entries via:

     'limit' => 1000, // config/telescope.php
     

   • Use telescope:prune to clean old entries:

     php artisan telescope:prune --hours=24
     

2. Database Bloat

   • The telescope_entries table grows rapidly. Monitor size and prune aggressively in staging:

     php artisan telescope:prune --hours=1
     

3. Middleware Conflicts

   • Telescope’s middleware may interfere with CSRF or auth checks. Exclude routes:

     Route::middleware(['web', 'telescope.screenshots'])->group(function () {
         // Exclude sensitive routes
     });
     

4. Asset Compilation

   • Telescope uses Vite for assets. If assets fail to compile, run:

     npm run dev
     

   • Clear compiled assets if issues persist:

     php artisan telescope:clear && npm run dev
     

Debugging Tips

• Missing Entries: Ensure TELESCOPE_ENABLED=true and the telescope middleware is registered.
• Query Formatting: Use DB::enableQueryLog() for raw SQL inspection. Telescope formats queries but may miss context.
• Job Payloads: For large payloads, use Telescope::log() with serialize: false to avoid bloating entries:

  Telescope::log('Job Payload', ['data' => $job->payload], serialize: false);
  

Extension Points

1. Custom Watchers

   • Extend Telescope to monitor custom events (e.g., cache misses):

     use Laravel\Telescope\Contracts\Watcher;
     
     class CacheWatcher implements Watcher {
         public function report($payload) {
             return [
                 'message' => 'Cache miss',
                 'key' => $payload['key'],
             ];
         }
     }
     

   • Register in AppServiceProvider@boot():

     Telescope::make()->extend(CacheWatcher::class);
     

2. Filtering Entries

   • Override the default query builder in AppServiceProvider:

     use Laravel\Telescope\Telescope;
     
     Telescope::filter(function ($query) {
         return $query->where('tags', 'like', '%api%');
     });
     

3. Localization

   • Translate Telescope’s UI by publishing lang files:

     php artisan vendor:publish --tag=telescope-lang
     

   • Override in resources/lang/en/telescope.php.

4. Security

   • Restrict access to Telescope in config/telescope.php:

     'middleware' => ['auth:sanctum', 'verified'],
     

   • Use IP whitelisting for local environments:

     'local' => [
         'middleware' => ['throttle:100'],
     ],