Telescope Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/telescope --dev
   

   Add to config/app.php under providers:

   Laravel\Telescope\TelescopeServiceProvider::class,
   

   And to aliases:

   'Telescope' => Laravel\Telescope\TelescopeFacade::class,
   

2. Publish Configuration & Migrations:

   php artisan telescope:install
   

   This runs migrations and publishes config/assets.

3. Run Migrations:

   php artisan migrate
   

4. Enable Telescope Middleware: Add to routes/web.php (or routes/api.php for API routes):

   Telescope::routes()->middleware('web');
   

   Or for API-only:

   Telescope::routes()->middleware('api');
   

5. Access Telescope: Visit /telescope in your browser. Authenticate via Laravel’s default auth (or configure custom auth in config/telescope.php).

First Use Case: Debugging a Request

• Trigger a request to your application (e.g., visit a route or submit a form).
• Navigate to /telescope and click the latest Request entry.
• Inspect:
  • Request/Response Headers: Check HTTP headers.
  • Query Log: View all executed SQL queries with bindings and execution time.
  • Exceptions: See any thrown errors.
  • Dumps: Review dd() or dump() outputs from your code.
  • Jobs/Tasks: Monitor queued jobs or scheduled tasks.

Key Shortcuts

• Clear Entries: php artisan telescope:clear
• Prune Old Entries: php artisan telescope:prune (configurable in config/telescope.php).
• Toggle Tracking: Disable tracking for specific entries via config/telescope.php:

  'ignore_routes' => [
      'telescope',
      'horizon',
  ],
  

Implementation Patterns

1. Request Debugging Workflow

• Middleware Integration: Add custom middleware to log specific data:

  use Laravel\Telescope\IncomingRequest;
  
  public function handle($request, Closure $next) {
      IncomingRequest::createFromRequest($request)->store();
      return $next($request);
  }
  

  Register in app/Http/Kernel.php:

  protected $middleware = [
      \App\Http\Middleware\LogRequestToTelescope::class,
  ];
  

• Filtering Requests: Exclude sensitive routes (e.g., API endpoints) in config/telescope.php:

  'ignore_routes' => [
      'api/*',
  ],
  

2. Query Optimization

• Slow Query Identification: Sort queries by execution time in Telescope’s Queries tab. Example SQL tuning:

  // Before (N+1 problem)
  $posts = Post::all();
  foreach ($posts as $post) {
      $post->comments; // Separate query per post
  }
  
  // After (Eager loading)
  $posts = Post::with('comments')->get();
  

• Binding Inspection: Click a query in Telescope to see raw bindings and adjust your Eloquent queries.

3. Exception Handling

• Track Custom Exceptions: Extend Telescope\Entry to log custom data:

  use Laravel\Telescope\Entries\Entry;
  
  class CustomExceptionEntry extends Entry
  {
      public function __construct($exception)
      {
          parent::__construct('exception', $exception);
          $this->data['custom_field'] = $exception->getCustomData();
      }
  }
  

  Register in AppServiceProvider:

  public function boot()
  {
      Telescope::catchExceptions(function ($exception) {
          return new CustomExceptionEntry($exception);
      });
  }
  

4. Job & Task Monitoring

• Queue Worker Debugging: Use Telescope to track job failures:

  // In a job
  try {
      // Job logic
  } catch (\Exception $e) {
      throw $e; // Will appear in Telescope's "Jobs" tab
  }
  

  Filter failed jobs in Telescope’s UI or via:

  Telescope::filter(function ($query) {
      return $query->where('type', 'job')->where('is_failed', true);
  });
  

5. Custom Data Dumps

• Log Variables: Use Telescope::dump($variable) anywhere in your code:

  use Laravel\Telescope\Telescope;
  
  public function someMethod()
  {
      $user = User::find(1);
      Telescope::dump($user->posts); // Appears in "Dumps" tab
  }
  

• Conditional Dumping:

  if (app()->environment('local')) {
      Telescope::dump($sensitiveData);
  }
  

6. Integration with Tests

• Test Debugging: Add to phpunit.xml:

  <env name="TELESCOPE_ENABLED" value="true"/>
  

  Use in tests:

  public function testSomething()
  {
      $this->withoutExceptionHandling();
      // Test logic
      $this->assertDatabaseHas('telescope_entries', [
          'type' => 'request',
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Telescope adds ~10-20ms per request. Disable in production:

     'enabled' => env('TELESCOPE_ENABLED', false),
     

   • Use telescope:prune to limit storage (default: 14 days).

2. Sensitive Data Leaks:

   • Never expose Telescope in production. Use middleware to restrict access:

     Telescope::routes()->middleware(['web', 'auth']);
     

   • Redact sensitive data in dumps:

     Telescope::macro('dump', function ($data) {
         if (is_array($data) && isset($data['password'])) {
             $data['password'] = '[REDACTED]';
         }
         return \Laravel\Telescope\Telescope::dump($data);
     });
     

3. Database Bloat:

   • Large applications may fill telescope_entries quickly. Adjust retention:

     'prune' => [
         'after' => '14 days',
         'retention' => '1 year',
     ],
     

4. Asset Compilation Issues:

   • After updating Telescope, run:

     npm run dev
     npm run build
     

   • If using Vite (Laravel 10+), ensure vite.config.js includes Telescope assets:

     import { defineConfig } from 'vite';
     import laravel from 'laravel-vite-plugin';
     
     export default defineConfig({
         plugins: [
             laravel({
                 input: ['resources/css/app.css', 'resources/js/app.js', 'resources/js/telescope.js'],
             }),
         ],
     });
     

Debugging Tips

1. Missing Entries:

   • Ensure TelescopeServiceProvider is registered and migrations ran.
   • Check config/telescope.php for ignore_routes or ignore_exceptions.

2. Query Log Not Showing:

   • Verify DB::enableQueryLog() is not disabled globally.
   • Clear cached queries:

     php artisan telescope:clear
     

3. Authentication Issues:

   • Default auth uses Laravel’s auth middleware. For custom auth:

     Telescope::auth(function ($request) {
         return $request->user()->isAdmin();
     });
     

4. Job Tracking Gaps:

   • Ensure TelescopeServiceProvider is loaded before queue workers.
   • For Horizon, add to config/horizon.php:

     'middleware' => ['web', 'auth'],
     

Extension Points

1. Custom Entry Types: Extend Laravel\Telescope\Entries\Entry to log application-specific events:

   class PaymentEntry extends Entry
   {
       public function __construct($payment)
       {
           parent::__construct('payment', $payment);
           $this->data['amount'] = $payment->amount;
           $this->data['status'] = $payment->status;
       }
   }
   

   Register in AppServiceProvider:

   public function boot()
   {
       Telescope::macro('logPayment', function ($payment) {
           return new PaymentEntry($payment);
       });
   }
   

2. Override Serialization: Customize how objects are serialized for dumps:

   Telescope::macro('