Nova Tail Tool Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require spatie/nova-tail-tool
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Spatie\NovaTailTool\NovaTailToolServiceProvider"
   

2. Register the Tool Add the tool to your Nova tools() method in app/Providers/NovaServiceProvider.php:

   public function tools()
   {
       return [
           // ... other tools
           new \Spatie\NovaTailTool\NovaTailTool,
       ];
   }
   

3. First Use Case

   • Access the tool via Nova’s sidebar.
   • Start tailing logs in real-time (default: storage/logs/laravel.log).
   • Filter logs by level (e.g., error, info) or search for specific terms.

Implementation Patterns

Core Workflows

1. Real-Time Log Monitoring

   • Use the tool to tail logs live during development or debugging.
   • Supports auto-refresh (configurable interval) for non-real-time environments.

2. Log Filtering & Search

   • Filter logs by level (e.g., error, warning) via dropdown.
   • Search logs using keyword matching (case-insensitive).
   • Example: Search for authentication errors during a login bug.

3. Multi-Environment Logs

   • Configure different log paths per environment in config/nova-tail-tool.php:

     'log_files' => [
         'local' => storage_path('logs/laravel.log'),
         'production' => '/var/www/storage/logs/laravel.log',
     ],
     

   • Switch log files dynamically via the tool’s dropdown.

4. Integration with Nova Actions

   • Trigger log tailing from a Nova action (e.g., post-deployment):

     public function handle()
     {
         NovaTailTool::tail(); // Redirects to the tool with pre-configured settings
     }
     

5. Customizing Log Display

   • Extend the tool’s log formatter to highlight specific patterns (e.g., API requests):

     NovaTailTool::macro('formatLog', function ($log) {
         return preg_replace('/"user_id": (\d+)/', '<span class="text-yellow-500">"user_id": $1</span>', $log);
     });
     

Gotchas and Tips

Pitfalls

1. Permission Issues

   • Ensure the Nova server has read access to log files (e.g., storage/logs/).
   • Fix with:

     chmod -R 755 storage/logs/
     

   • For production, use a symlink to a writable directory:

     ln -s /var/www/storage/logs /path/to/writable/logs
     

2. High-Volume Logs

   • Tail tool may lag with large log files (>10MB).
   • Workaround: Use logrotate to split logs or configure max_lines in config:

     'max_lines' => 1000, // Limits displayed logs
     

3. Environment-Specific Paths

   • Hardcoded paths (e.g., storage_path('logs/laravel.log')) break in shared hosting.
   • Tip: Use env('LOG_FILE') or publish the config to customize per environment.

4. Real-Time vs. Polling

   • The tool uses JavaScript polling (not native tailing).
   • Tip: For true real-time, pair with Laravel Echo/Pusher to push log events.

Debugging

• Logs Not Loading? Check the browser’s Network tab for failed requests to /nova/v1/nova-tail-tool/logs.

  • Verify the log file path in config/nova-tail-tool.php.
  • Ensure the Nova server can read the file (test with file_exists() in Tinker).

• Stale Logs? Clear cached views:

  php artisan view:clear
  

  Or restart Nova’s queue worker if using background processing.

Extension Points

1. Custom Log Sources Override the default log source (e.g., database logs):

   NovaTailTool::macro('getLogSource', function () {
       return new CustomLogSource();
   });
   

2. Add Context to Logs Enhance logs with clickable links (e.g., user IDs):

   NovaTailTool::macro('formatLog', function ($log) {
       return str_replace(
           'user_id=123',
           '<a href="/nova/users/123" target="_blank">user_id=123</a>',
           $log
       );
   });
   

3. Log Level Colors Customize CSS for log levels in resources/css/nova-tail-tool.css:

   .log-error { color: #ff0000; }
   .log-info { color: #00aa00; }
   

4. API Access Fetch logs programmatically via Nova’s API:

   $logs = Http::withHeaders([
       'Accept' => 'application/json',
       'Authorization' => 'Bearer ' . $novaToken,
   ])->get('nova/v1/nova-tail-tool/logs');