Telescope Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   This publishes the migration, config, and assets, then registers the Telescope service provider.

2. Database Migration:

   php artisan migrate
   

   Creates the telescope_entries table.

3. Middleware Registration: Add TelescopeServiceProvider::class to config/app.php under providers (if not auto-discovered). Add TelescopeScreenshots::class to app/Http/Middleware/ and register it in app/Http/Kernel.php:

   'web' => [
       \Illuminate\Foundation\Http\Middleware\CheckForMaintenanceMode::class,
       \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
       \App\Http\Middleware\TelescopeScreenshots::class, // Add this line
       \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
       // ...
   ],
   

4. First Use: Visit http://your-app.test/telescope (or /telescope in production if configured). Authenticate via Laravel’s default auth (e.g., php artisan make:auth if using older Laravel).

Key Features to Explore First

• Requests: Inspect HTTP requests, responses, and headers.
• Exceptions: Debug errors with stack traces and context.
• Queries: Analyze slow database queries with execution time and bindings.
• Dumps: View variable dumps from dd() or dump() calls.
• Jobs: Monitor queued jobs, including payloads and exceptions.

Implementation Patterns

Daily Workflows

1. Debugging Requests

• Pattern: Use Telescope to trace a specific request.
  • Steps:
    1. Trigger the request (e.g., via browser or Postman).
    2. Navigate to Requests in Telescope.
    3. Filter by method, uri, or tags (e.g., api).
    4. Click a request to see:
       • Headers, payload, and response.
       • Related entries (queries, jobs, logs) via the "Related" tab.
  • Pro Tip: Tag requests in middleware:

    public function handle($request, Closure $next) {
        $request->telescope()->tag('api', 'v1');
        return $next($request);
    }
    

2. Query Optimization

• Pattern: Identify N+1 queries or slow queries.
  • Steps:
    1. Navigate to the Queries tab.
    2. Sort by duration (descending).
    3. Click a query to see:
       • Bindings, execution time, and SQL.
       • Related models (if using Eloquent).
  • Pro Tip: Use telescope:clear to reset data:

    php artisan telescope:clear
    

3. Job Monitoring

• Pattern: Debug failed or delayed jobs.
  • Steps:
    1. Navigate to the Jobs tab.
    2. Filter by status (e.g., failed).
    3. Click a job to see:
       • Payload, exceptions, and related entries.
  • Pro Tip: Configure queue delay visibility in config/telescope.php:

    'queues' => [
        'delay' => true, // Show delayed jobs
    ],
    

4. Variable Dumps

• Pattern: Replace dd() with Telescope for persistent debugging.
  • Steps:
    1. Use dump() or dd() in your code.
    2. Navigate to the Dumps tab.
    3. Filter by context (e.g., route, controller).
  • Pro Tip: Customize dump serialization in AppServiceProvider:

    use Illuminate\Support\Facades\Telescope;
    
    public function boot() {
        Telescope::extend(function ($telescope) {
            $telescope->watchVariableDumps(function ($dumper) {
                $dumper->with(new CustomDumper());
            });
        });
    }
    

5. Exception Tracking

• Pattern: Correlate exceptions with requests and queries.
  • Steps:
    1. Trigger an exception (e.g., abort(500)).
    2. Navigate to the Exceptions tab.
    3. Click an exception to see:
       • Stack trace, context, and related entries.
  • Pro Tip: Filter exceptions by type or message:

    // In a middleware or service provider
    Telescope::filter(function ($entry) {
        return !$entry instanceof \Illuminate\Exceptions\Handler;
    });
    

Integration Tips

1. Environment-Specific Configuration

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

  TELESCOPE_ENABLED=false
  

• Restrict access via middleware:

  protected function authenticate(): void {
      if (! auth()->check()) {
          abort(403);
      }
  }
  

2. Customizing Entry Storage

• Extend Telescope to store additional data:

  use Illuminate\Support\Facades\Telescope;
  
  Telescope::extend(function ($telescope) {
      $telescope->watchCommands(function ($command) {
          return [
              'command' => $command,
              'exit_code' => 0,
          ];
      });
  });
  

3. Screen Customization

• Add a custom screen (e.g., for API metrics):

  use Illuminate\Support\Facades\Telescope;
  
  Telescope::screen(function () {
      return \App\Screens\ApiMetricsScreen::make();
  });
  

4. Queue Listeners

• Monitor queue workers in real-time:

  php artisan queue:work --telescope
  

5. CI/CD Integration

• Disable Telescope in CI by checking the environment:

  if (app()->environment('ci')) {
      Telescope::ignoreRoutes(function () {
          return true;
      });
  }
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Telescope adds latency to requests and queries. Solution: Disable in production and use sparingly in staging.
   • Monitor query performance with DB::enableQueryLog() and compare with Telescope data.

2. Database Bloat:

   • Telescope entries accumulate over time. Solution:
     • Clear entries regularly:

       php artisan telescope:clear
       

     • Set retention in config/telescope.php:

       'retention' => 14, // Days to keep entries
       

3. Authentication Bypass:

   • Telescope routes are public by default. Solution:
     • Use Laravel’s auth middleware or IP filtering:

       Telescope::auth(function () {
           return auth()->check();
       });
       

4. Missing Related Entries:

   • Some entries (e.g., jobs) may not show related queries. Solution:
     • Ensure TelescopeScreenshots middleware is registered.
     • Manually link entries via telescope()->associate():

       $entry = Telescope::entry('request');
       $entry->associate($queryEntry);
       

5. SQL Formatting Issues:

   • Complex queries may not format correctly. Solution:
     • Use the sql-formatter package or manually format in Telescope’s query view.

Debugging Tips

1. Disable Specific Features:

   • Turn off queries, logs, or exceptions in config/telescope.php:

     'enable-queries' => env('TELESCOPE_QUERIES', false),
     'enable-logging' => env('TELESCOPE_LOGGING', false),
     

2. Filter Noisy Entries:

   • Ignore specific routes or IPs:

     Telescope::ignoreRoutes(function ($request) {
         return $request->ip() === '127.0.0.1';
     });
     

3. Inspect Binary Content:

   • For large payloads (e.g., file uploads), use the "Download" button or check raw data in the database.

4. Telescope Not Loading Assets:

   • Ensure assets are published and compiled:

     php artisan telescope:assets
     npm run dev
     

5. PHP Errors in Telescope:

   • Check storage/logs/laravel.log for Telescope-specific errors.
   • Clear compiled views:

     php artisan view:clear
     

Extension Points

1. Custom Entry Types:
   • Extend Telescope to log custom events:

     Telescope::extend(function ($telescope) {
         $telescope->watchCustomEvents(function ($event) {
             return [
                 'name'