【Laravel11】ログ追跡パッケージPailを使ってみた

ログ追跡用のLaravel公式パッケージPailを使ってみました。

Laravel - The PHP Framework For Web Artisans

Laravel is a PHP web application framework with expressive, elegant syntax. We???ve already laid the foundation ??? free...

GitHub - laravel/pail: Dive into your Laravel application's log files directly from the console. 🪣

Dive into your Laravel application's log files directly from the console. 🪣 - laravel/pail

Laravel Pail とは
前提条件
Laravelプロジェクト作成
Laravel Pail インストール
ログ生成コマンド作成
基本的な使い方
フィルタリングオプション
通常フィルタリング
メッセージフィルタリング
ログレベルフィルタリング
ユーザーIDフィルタリング

Laravel Pail とは

Laravelチームが提供しているログ追跡用のパッケージです。

Laravel Pail は、コマンドラインから直接 Laravel アプリケーションのログファイルに簡単にアクセスできるパッケージです。標準の tail コマンドとは異なり、Pail は Sentry や Flare を含むあらゆるログドライバーで動作するように設計されています。さらに、Pail は、探しているものをすばやく見つけるのに役立つ一連の便利なフィルターを提供します。

前提条件

PHP8.2以降インストール済
Laravel11を使っていきます（Laravel10でも可）
Composerインストール済
PHP PCNTL(プロセス制御)拡張有効化済

PHP PCNTL拡張については、PHPコアのデフォルトインストールでは無効化されているようです。

phpenvでインストールする場合はデフォルトで有効化されています。

次のコマンドで有効/無効の確認ができます。

php -i | grep pcntl

Configure オプションで「–enable-pcntl」が適用された状態でPHPがコンパイルされている必要があります。

Laravelプロジェクト作成

新規プロジェクト「pail-app」を作成します。

composer create-project laravel/laravel:^11 pail-app

プロジェクトフォルダに入ります。

cd pail-app

Laravel Pail インストール

Laravel Pail はデフォルトで開発環境用にインストールされています。

▼「composer.json」抜粋

    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.31",
        "laravel/tinker": "^2.9"
    },
    "require-dev": {
        "fakerphp/faker": "^1.23",
        "laravel/pail": "^1.1", // ←開発環境用にインストール済
        "laravel/pint": "^1.13",
        "laravel/sail": "^1.26",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.1",
        "phpunit/phpunit": "^11.0.1"
    },

無い場合は、Composerを使って Pail をインストールします。

composer require laravel/pail --dev

ログ生成コマンド作成

ログを生成するコマンドを作成してみます。

php artisan make:command FakeLogCommand

「app/Console/Commands/FakeLogCommand.php」を編集します。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Log;

class FakeLogCommand extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'fake:log';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Log Faker';

    /**
     * Execute the console command.
     */
    public function handle()
    {
        Log::emergency($this->fakeMessage());
        Log::alert($this->fakeMessage());
        Log::critical($this->fakeMessage());
        Log::error($this->fakeMessage());
        Log::warning($this->fakeMessage());
        Log::notice($this->fakeMessage());
        Log::info($this->fakeMessage());
        Log::debug($this->fakeMessage());
    }

    public function fakeMessage()
    {
        return implode(PHP_EOL, fake()->paragraphs(3));
    }
}

基本的な使い方

Laravel Pail を起動します。

php artisan pail

プロジェクト作成直後には「storage/logs/laravel.log」が無いので何も表示されませんが、「tail -f storage/logs/laravel.log」とは違ってエラーが出ることはありません。

では、別のターミナルでログ生成コマンドを実行してログ出力してみましょう。

php artisan fake:log

pailのターミナルが更新されます。

ログレベルにより色分けされて見やすいようになっています。

また、デフォルトの場合、長いメッセージは省略されます。

pail起動時に「-v」「-vv」オプションを付けるとメッセージが長く表示されます。

[Ctrl] + [C] で強制終了です。

tail コマンドの場合と見比べてみましょう。

tail -f storage/logs/laravel.log

フィルタリングオプション

Pailのフィルタリングオプションは次のようになっています。

オプション	説明
–filter	通常フィルタリング
–message	メッセージフィルタリング
–level	ログレベルフィルタリング
–user	USER IDフィルタリング

通常フィルタリング

フィルターの対象は

type
file
message
stack trace content

となっています。

Pailを実行すると、一時ファイル「storage/pail/***.pail」が作成されます。

内容はログを１行ずつオブジェクト化してシリアライズしたもののようです。

１行分を整形したものは次のようになっています。

{
	"message": "Hoge!",
	"context": {
		"exception": {
			"class": "Exception",
			"message": "Hoge!",
			"code": 0,
			"file": "/home/macocci7/work/pail-app/app/Console/Commands/FakeLogCommand.php:37"
		},
		"__pail": {
			"origin": {
				"type": "console",
				"command": "fake:log",
				"trace": [
					{
						"file": "/home/macocci7/work/pail-app/vendor/laravel/framework/src/Illuminate/Container/BoundMethod.php",
						"line": 36
					},
・・・（中略）・・・
					{
						"file": "/home/macocci7/work/pail-app/artisan",
						"line": 13
					}
				]
			}
		}
	},
	"level": 400,
	"level_name": "ERROR",
	"channel": "pail",
	"datetime": "2024-12-01T02:33:15.666632+00:00",
	"extra": {}
}

この中のプロパティがフィルター対象のようです。

使い方の例は次の通りです。

php artisan pail --filter="2024-12-01"

メッセージフィルタリング

メッセージの文面をフィルタリングします。

使い方の例は次の通りです。

php artisan pail --message="Quas"

ログレベルフィルタリング

対象となるログレベルは次の通りです。

emergency
alert
critical
error ・・・（exceptionを含む)
warning
notice
info
debug

使い方の例は次の通りです。

php artisan pail --level=error

ユーザーIDフィルタリング

フィルタ対象はログインユーザーのIDです。

使い方の例は次の通りです。

php artisan pail --user=1

ログイン機構準備のためにBreezeをインストールしてみます。

composer require laravel/breeze

php artisan breeze:install

マイグレーションのシーダーを使ってtestユーザーを作成します。

php artisan migrate --seed

※email=test@example.com、password=password のユーザーが作成されます。

Laravelのビルトインサーバーを起動します。

php artisan serve

ログ出力のためにログイン後のルーティングを追加しておきます。

「routes/web.php」を編集します。

※冒頭に追記

use Illuminate\Support\Facades\Log;

※末尾に追記

Route::get('hoge', function () {
    Log::debug('User [' . auth()->user()->name . '] logged in.');
    return "Hoge!";
})->middleware('auth');

では、PailをユーザーIDフィルタリングオプション付きで起動してみます。

php artisan pail --user=1

WEBブラウザで http://localhost:8000/hoge にアクセスしてみます。

先程作成したテストユーザーでログインします。

ログ出力用のページが表示されました。

Pail のターミナルにログが出力されました。

他のユーザーでログインしてアクセスした場合、

ログには出力されますが、Pailのターミナルには出力されません。

新規ユーザー登録してからアクセスしてみると判ります。

以上です。