Log Viewer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require opcodesio/log-viewer
   php artisan log-viewer:publish
   

   • Publishes assets and config files to resources/views/vendor/log-viewer and config/log-viewer.php.

2. Access:

   • Visit /log-viewer in your browser (default route).
   • No additional setup required for basic Laravel logs (storage/logs/laravel.log).

3. First Use Case:

   • Debug a production error by filtering logs by log level (e.g., error) or searching for a specific exception class (e.g., QueryException).
   • Use the sharable link feature to send a direct link to a teammate for collaborative debugging.

Implementation Patterns

Core Workflows

1. Log Exploration:

   • Folder Navigation: Browse log files (Laravel, Horizon, Nginx, etc.) in a tree view.
   • Log Filtering: Use the UI dropdown to filter by log levels (debug, info, warning, error, critical).
   • Search: Instantly search across all logs with keyword highlighting (e.g., failed, timeout).

2. Advanced Features:

   • Stack Trace Visualization:

     // Enable in config/log-viewer.php:
     'stack_trace' => [
         'enabled' => true,
     ]
     

     • Click a log entry with a stack trace to expand it in a dedicated tab.
   • Mail Previews: View sent emails directly in the log viewer if using Laravel’s Log::channel('mail').

3. API Integration:

   • Fetch logs programmatically via the API endpoint (/api/log-viewer):

     $logs = Http::get('/api/log-viewer/folders');
     $entries = Http::get('/api/log-viewer/folders/{folder}/files/{file}/entries');
     

   • Useful for custom dashboards or CI/CD log analysis.

4. Custom Log Parsers:

   • Extend support for unsupported log formats (e.g., custom JSON logs):

     // config/log-viewer.php
     'log_types' => [
         'custom_json' => [
             'parser' => \Opcodes\LogViewer\Parsers\CustomJsonParser::class,
             'path' => storage_path('logs/custom/*.json'),
         ],
     ],
     

   • Implement a parser by extending Opcodes\LogViewer\Parsers\ParserInterface.

5. Multi-Host Support:

   • Configure remote log directories in config/log-viewer.php:

     'remote_logs' => [
         'ssh://user@remote-server:/var/log/myapp' => [
             'driver' => 'ssh',
             'username' => env('REMOTE_LOG_USER'),
             'password' => env('REMOTE_LOG_PASSWORD'),
         ],
     ],
     

Integration Tips

• Authentication: Protect the /log-viewer route in routes/web.php:

  Route::middleware(['auth'])->group(function () {
      Route::get('/log-viewer', [\Opcodes\LogViewer\Http\Controllers\LogViewerController::class, 'index']);
  });
  

• Asset Customization: Override the default Vue.js assets by publishing and modifying:

  php artisan vendor:publish --tag=log-viewer-assets
  

  • Edit resources/views/vendor/log-viewer/assets/js/app.js for custom UI behavior.
• Octane Compatibility: Use scoped bindings for Octane (Laravel 11+):

  // config/log-viewer.php
  'octane' => [
      'scoped_bindings' => true,
  ],
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Symptom: Logs fail to load with "Permission denied" errors.
   • Fix: Ensure the web server user (e.g., www-data, nginx) has read access to log directories:

     chmod -R 755 storage/logs/
     chown -R www-data:www-data storage/logs/
     

   • For remote logs (SSH), verify credentials and SSH key permissions.

2. Log Format Mismatches:

   • Symptom: Logs appear as raw text or are misparsed.
   • Fix: Check supported log formats here. For custom formats, implement a parser (see Custom Parsers).

3. API Authentication Failures:

   • Symptom: API endpoints return 401 Unauthorized even with valid tokens.
   • Fix: Ensure APP_URL is set in .env and the API route is properly authenticated:

     // routes/api.php
     Route::middleware('auth:sanctum')->group(function () {
         Route::prefix('log-viewer')->group(\Opcodes\LogViewer\Routes\Api::routes());
     });
     

4. Horizon Log Gaps:

   • Symptom: Horizon logs are missing or incomplete.
   • Fix: Ensure Horizon is configured to log to a supported format (e.g., single or database). Update the parser in config/log-viewer.php:

     'log_types' => [
         'horizon' => [
             'parser' => \Opcodes\LogViewer\Parsers\HorizonParser::class,
             'path' => storage_path('logs/horizon/*.log'),
         ],
     ],
     

5. Asset Caching:

   • Symptom: UI changes (e.g., custom CSS) aren’t reflected.
   • Fix: Clear Laravel’s cache and config:

     php artisan cache:clear
     php artisan config:clear
     

   • For runtime Vue bundler issues, delete bootstrap/cache and reload.

Debugging Tips

• Log Parser Debugging:

  • Enable debug mode in config/log-viewer.php:

    'debug' => true,
    

  • Check Laravel logs (storage/logs/laravel.log) for parser errors.

• API Debugging:

  • Use Postman or Laravel’s Http::debug(true) to inspect API responses:

    Http::debug(true);
    $response = Http::get('/api/log-viewer/folders');
    

• Performance:

  • Large log files (>100MB) may cause slow loading. Optimize with:

    // config/log-viewer.php
    'pagination' => [
        'items_per_page' => 50, // Default: 100
    ],
    

Extension Points

1. Custom UI Components:

   • Override the Vue.js app by extending the default component:

     // resources/js/log-viewer/app.js
     import DefaultApp from '@opcodes/log-viewer/dist/js/app';
     export default {
         extends: DefaultApp,
         methods: {
             customMethod() {
                 // Add custom logic
             }
         }
     };
     

2. Log Annotations:

   • Add custom metadata to logs by extending the LogEntry model or using middleware:

     // app/Http/Middleware/AnnotateLogs.php
     public function handle($request, Closure $next) {
         Log::withContext(['user_id' => auth()->id()]);
         return $next($request);
     }
     

3. Webhook Notifications:

   • Trigger alerts for critical logs using Laravel’s Log::listen:

     Log::listen(function ($level, $message, array $context) {
         if ($level === 'error' && str_contains($message, 'Database')) {
             Http::post('https://your-webhook-url', ['log' => $message]);
         }
     });
     

4. Dark Mode Toggle:

   • Customize the dark mode theme by overriding the CSS:

     /* resources/css/log-viewer/app.css */
     .log-viewer-dark .log-entry {
         background-color: #1a1a1a;
     }
     

Configuration Quirks

• Assets Path:

  • Starting with v3.19, the assets path is configurable:

    // config/log-viewer.php
    'assets' => [
        'path' => public_path('custom-log-viewer-assets'),
    ],
    

  • Set to null to serve assets directly from the vendor directory (no publishing needed).

• Local IP in Hashes:

  • Disable local IP scoping for consistent file/folder hashes across machines:

    // config/log-viewer.php
    'hashing' => [
        'use_local_ip' => false,
    ],
    

• Mail Parser:

  • Ensure the mail parser is enabled for email log previews:

    // config/log-viewer.php
    'mail' => [
        'enabled' => true,
        'path' => storage_path('logs/mail.log'),
    ],