Log Tail Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cethyworks/log-tail-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+):

   return [
       // ...
       Cethyworks\LogTailBundle\CethyworksLogTailBundle::class => ['all' => true],
   ];
   

2. First Use Case: Run the prettified tail -f command directly via Artisan:

   php artisan debug:log:tail
   

   • Defaults to tailing var/log/dev.log (hardcoded).
   • Optional --interval flag (e.g., --interval=2 for 2-second refreshes).

3. Where to Look First:

   • Command Class: src/Command/DebugLogTailCommand.php (core logic).
   • Hardcoded Paths: Check getLogFile() in the command for default paths.
   • Output Formatting: Inspect formatLine() for prettification logic (e.g., timestamps, colors).

Implementation Patterns

Usage Patterns

1. Tail Specific Logs: Override the hardcoded path by extending the command:

   // app/Console/Commands/TailCustomLog.php
   namespace App\Console\Commands;
   use Cethyworks\LogTailBundle\Command\DebugLogTailCommand;
   
   class TailCustomLog extends DebugLogTailCommand {
       protected function getLogFile() {
           return storage_path('logs/custom.log');
       }
   }
   

   Register the new command in app/Console/Kernel.php.

2. Integration with Laravel Logging: Use the bundle alongside Laravel’s logging system:

   # Tail the default Laravel log
   php artisan debug:log:tail
   
   # Tail a monolog channel (e.g., 'single')
   php artisan debug:log:tail --log-channel=single
   

   (Note: Requires extending the bundle to support channels—see "Extension Points" below.)

3. Workflow: Debugging in Real-Time:

   • Dev Environment: Use during local development to monitor logs without tail -f in the terminal.
   • CI/CD: Disable in production (see "Gotchas").
   • Collaboration: Share prettified logs via screenshots or embed in Slack (e.g., using pipes to forward output).

Integration Tips

• Symfony Console Integration: Add the command to your bin/console aliases for easier access:

  # config/packages/console.yaml
  console:
      commands:
          debug:log:tail: 'Cethyworks\LogTailBundle\Command\DebugLogTailCommand'
  

• Custom Formatting: Extend the formatLine() method to add:
  • Log levels (e.g., [INFO], [ERROR]).
  • File/line numbers (if available in log format).
  • ANSI colors for severity highlighting.
• Environment-Specific Config: Use Laravel’s config to override paths:

  // config/log-tail.php
  return [
      'log_path' => env('LOG_TAIL_PATH', 'var/log/dev.log'),
  ];
  

  Then inject this into the command via dependency injection.

Gotchas and Tips

Pitfalls

1. Hardcoded Dependencies:

   • Log file paths (var/log/dev.log) are hardcoded. Override getLogFile() or patch the bundle.
   • No support for log rotation or dynamic log paths (e.g., storage/logs/laravel-*.log).
   • Workaround: Extend the command or fork the package.

2. Performance Overhead:

   • Real-time tailing consumes resources. Avoid running in production or long-lived processes.
   • Tip: Use --interval=1 for a balance between responsiveness and CPU usage.

3. Output Formatting Issues:

   • Prettification may break with non-standard log formats (e.g., JSON logs).
   • Fix: Extend formatLine() to handle custom formats:

     protected function formatLine(string $line): string {
         if (str_starts_with($line, '[')) {
             return $line; // Skip prettification for JSON
         }
         return parent::formatLine($line);
     }
     

4. Missing Features:

   • No support for filtering logs by level (e.g., --level=error).
   • No follow-up (-f) toggle (always tails).
   • Tip: Pipe output to grep for filtering:

     php artisan debug:log:tail 2>&1 | grep -i "error"
     

5. Archived Package Risks:

   • No updates or maintenance. Use at your own risk.
   • Mitigation: Fork the repo and maintain it internally.

Debugging

• Command Not Found: Ensure the bundle is registered in config/bundles.php and dependencies are installed.
• Permission Denied: Log files may require chmod or SELinux adjustments:

  chmod 644 var/log/dev.log
  

• Empty Output: Verify the log file exists and the path is correct. Add debug logs to the command:

  $this->info("Tailing file: " . $this->getLogFile());
  

Extension Points

1. Add Log Channel Support: Extend the command to read from Monolog channels:

   use Psr\Log\LoggerInterface;
   
   class ExtendedLogTailCommand extends DebugLogTailCommand {
       protected LoggerInterface $logger;
   
       public function __construct(LoggerInterface $logger) {
           $this->logger = $logger;
       }
   
       protected function getLogFile() {
           // Use Monolog's handlers to resolve the log file.
           // Requires deep integration with Monolog's stream handler.
       }
   }
   

   (Note: This requires significant refactoring of the original bundle.)

2. Custom Output Handlers: Replace the default output with a custom handler (e.g., write to a database):

   protected function outputLine(string $line) {
       // Custom logic (e.g., save to DB, send to Slack).
       parent::outputLine($line); // Fallback to default.
   }
   

3. Configuration via Laravel: Make the bundle configurable by adding a config file (config/log-tail.php) and binding it to the command:

   // In the command's constructor:
   public function __construct(array $config) {
       $this->config = $config;
   }
   

   Register the config in AppServiceProvider@boot():

   $this->app->bind(CethyworksLogTailBundleCommand::class, function ($app) {
       return new CethyworksLogTailBundleCommand(config('log-tail'));
   });
   

Tips

• Alias the Command: Add a shortcut in ~/.bashrc or ~/.zshrc:

  alias tail-logs='php artisan debug:log:tail'
  

• Combine with Other Tools: Use tmux or screen to run the command in a detached session:

  tmux new -s log-tail 'php artisan debug:log:tail'
  

• Log to a Named Pipe: For advanced use cases, tail a named pipe (FIFO) created by another process:

  mkfifo /tmp/laravel.log
  php artisan debug:log:tail --log-file=/tmp/laravel.log &
  # Another process writes to /tmp/laravel.log