Pail Laravel Package

Getting Started

Install the package via Composer:

composer require laravel/pail --dev

No service provider registration is needed—Pail auto-registers its console commands (pail:watch, pail:history). Start tailing logs instantly with:

php artisan pail:watch

Or view recent logs (default: last 50 lines) with:

php artisan pail:history

The first use case is typically debugging an issue in development by watching logs in real time while reproducing the bug (e.g., php artisan pail:watch --level=error). Pail now gracefully handles malformed JSON log lines, preventing crashes during log inspection.

Implementation Patterns

• Real-time debugging: Run php artisan pail:watch in a split terminal alongside your app while testing API endpoints, job dispatches, or notifications.
• Filtering by context or level: Use --level=debug or --context=userId:123 to narrow logs to specific scenarios (e.g., php artisan pail:watch --context=tenantId:42 --level=warn).
• Integrating with third-party drivers: Works out of the box with single, daily, stack, syslog, and external drivers like Sentry/Flare—no extra config needed.
• CI/CD diagnostics: Use php artisan pail:history in deployment pipelines to quickly surface recent exceptions when errors occur.
• Multiline log support: Automatically parses stack traces and multi-line exceptions (e.g., League\OAuth2\Server\Exception\OAuthServerException).
• Performance-optimized context: Avoids resolving the auth user when building log context, reducing overhead in high-traffic applications.

Gotchas and Tips

• Stale file handling: Pail detects log rotation; if logs disappear unexpectedly, check if your log driver rotates files (e.g., daily)—Pail handles this transparently via filemtime checks.
• Output clarity: Pail uses ANSI styling; avoid piping pail:watch to other commands that strip colors or break pagination (e.g., grep). Instead, use --filter="your pattern" for safe text searches.
• Timeout for non-tailing runs: The --timeout option (e.g., --timeout=5) is useful in scripts or CI jobs where you want to stream logs briefly without infinite hanging.
• Context-aware filtering: When logging with context (e.g., Log::info('Order processed', ['orderId' => 123])), you can grep only those entries: php artisan pail:watch --context=orderId:123.
• Lazy command loading: Commands are lazy-loaded (PHP 8.1+), so no performance penalty on app bootstrap—even in large projects.
• Silencing deprecation notices: From v1.2.3+, Pail suppresses Laravel’s own deprecation warnings by default—set APP_DEBUG=true and APP_LOG_LEVEL=debug if you need full detail.
• Malformed JSON resilience: Pail now skips malformed JSON log lines instead of crashing, ensuring smoother debugging sessions in environments with inconsistent log formatting.
• Auth user optimization: Avoids unnecessary auth user resolution when building log context, reducing latency in applications with heavy authentication checks.