Getting Started

Minimal Steps

Installation:
```
composer require laravel/pail --dev
```
(Note: Pail is automatically suggested as a dev dependency in Laravel 11+ via PR #56.)
First Use Case: Tail all logs in real-time:
```
php artisan log:tail
```
(Press Ctrl+C to exit.)
Key Flags for Immediate Use:
- Filter by log level (e.g., errors only):
```
php artisan log:tail --level=error
```
- Filter by context (e.g., auth-related logs):
```
php artisan log:tail --context=auth
```
- Limit output to recent logs (e.g., last 100 lines):
```
php artisan log:tail --lines=100
```
- Set a timeout (e.g., 30 seconds for CI/CD):
```
php artisan log:tail --timeout=30
```
Where to Look First:
- Official Docs: Laravel Logging Docs (covers all flags and use cases).
- Command Help:
```
php artisan log:tail --help
```
  (Lists all available options, including --since, --until, and --driver.)

Implementation Patterns

Core Workflows

Debugging Workflow:
- Step 1: Start tailing with filters:
```
php artisan log:tail --level=error --context=payment
```
- Step 2: Use keyboard shortcuts (e.g., ? for help, q to quit) to interactively refine filters.
- Step 3: Copy log entries directly from the terminal (e.g., for support tickets).

CI/CD Pipeline:

Validate logs in ephemeral environments:

php artisan log:tail --timeout=60 --level=critical

Exit with non-zero status on critical errors (integrate with set +e if needed):

if php artisan log:tail --timeout=30 --level=error | grep -q "Fatal"; then
  exit 1
fi

Production Monitoring:
- Tail logs in a shared environment (e.g., SSH):
```
php artisan log:tail --driver=single --since="1 hour ago"
```
- (Note: Use --driver=single for non-default log drivers like Sentry/Flare.)

Integration Tips

Custom Log Drivers:
- Pail works with any Monolog-compatible driver (e.g., Sentry, Flare, Syslog). Specify the driver explicitly:
```
php artisan log:tail --driver=sentry
```
- For Flare, ensure the flare log driver is configured in config/logging.php.
Multiline Logs:
- Pail natively supports multiline logs (added in v1.2.3). No additional configuration is required.
Log Context:
- Use --context to filter logs by arbitrary context data (e.g., user_id, request_id):
```
php artisan log:tail --context="user_id=123"
```
- (Note: Context must match the context array in your log messages.)

Time-Based Filtering:

Filter logs by timestamp:

php artisan log:tail --since="2024-01-01" --until="2024-01-02"

Relative time (e.g., "5 minutes ago"):

php artisan log:tail --since="-5 minutes"

Combining with Other Tools:

Pipe Pail output to grep or jq for further processing:

php artisan log:tail --level=debug | grep "database"

php artisan log:tail --level=info | jq '.context.request_id'

Automated Testing:

Use --timeout to test log output in isolated environments:
```
php artisan log:tail --timeout=10 --level=warning
```

Assert log messages in PHPUnit:

$this->artisan('log:tail --timeout=5 --level=error')
    ->expectsOutputToContain('Expected error message');

Advanced Patterns

Dynamic Filtering:
- Use --interactive to dynamically adjust filters without restarting the command:
```
php artisan log:tail --interactive
```
  (Press f to filter, then type your query.)

Log Archiving:

Export logs to a file for later analysis:

php artisan log:tail --timeout=300 --level=info > app_logs.txt

Custom Commands:

Extend Pail by creating a custom Artisan command that wraps log:tail with project-specific defaults:

// app/Console/Commands/TailPaymentLogs.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;

class TailPaymentLogs extends Command
{
    protected $signature = 'logs:payments';
    protected $description = 'Tail payment-related logs';

    public function handle()
    {
        $process = new Process(['php', 'artisan', 'log:tail', '--level=error', '--context=payment']);
        $process->run(function ($type, $output) {
            $this->output->write($output);
        });
    }
}

Gotchas and Tips

Pitfalls

Malformed JSON Logs:
- Issue: Pail may crash on malformed JSON log lines (fixed in v1.2.7).
- Workaround: Ensure your log messages are valid JSON. Use try-catch in your logging code:
```
try {
    Log::error('Malformed log', ['context' => 'data']);
} catch (\Exception $e) {
    Log::error("Failed to log: {$e->getMessage()}");
}
```
Auth User Resolution Overhead:
- Issue: Older versions of Pail resolved the authenticated user for every log entry, causing performance issues (fixed in v1.2.7).
- Tip: If using an older version, avoid --context with auth-related data or upgrade to v1.2.7+.
Multiline Log Parsing:
- Issue: Multiline logs may not display correctly if the log driver splits them across entries.
- Tip: Use --driver=single for file-based logs to ensure proper multiline handling.
Timezone Mismatches:
- Issue: Log timestamps may appear incorrect if the server and local timezones differ.
- Tip: Use --since/--until with UTC timestamps or set the TZ environment variable:
```
TZ=UTC php artisan log:tail --since="2024-01-01T00:00:00"
```
Non-Text Log Drivers:
- Issue: Pail won’t work with binary or non-text log drivers (e.g., some database loggers).
- Tip: Stick to Monolog-compatible drivers (e.g., single, daily, sentry, flare).
Deprecation Warnings:
- Issue: Pail may display deprecation notices for Laravel features (suppressed in v1.2.3).
- Tip: Ignore these warnings unless they affect functionality. Upgrade Laravel/Pail to resolve them.

Debugging Tips

Check Log Driver Configuration:
- Verify your config/logging.php has the correct default driver:
```
'default' => env('LOG_CHANNEL', 'single'),
```
- For remote drivers (e.g., Sentry), ensure the driver is properly configured.
Inspect Raw Log Files:
- If Pail behaves unexpectedly, check the raw log files:
```
tail -f storage/logs/laravel.log
```
- Compare output with Pail’s filtered view to identify discrepancies.
Enable Debug Mode:
- Run Pail with --verbose to see underlying issues:
```
php artisan log:tail --verbose
```
Handle Stale Log Files:
- If Pail reports "no logs found," the log file may be stale or locked. Restart

Pail Laravel Package