バージョン: master

ロギング (Logging)

Introduction
Configuration
ログスタックの構築
ログメッセージの書き込み
- コンテキスト情報
- 特定のチャネルへの書き込み
モノログチャンネルのカスタマイズ
Pail を使用したログメッセージの追跡

導入 (Introduction)

アプリケーション内で何が起こっているかを詳しく知るために、Laravel はメッセージをファイル、システムエラーログ、さらには Slack に記録してチーム全体に通知できる堅牢なログサービスを提供します。

Laravelのロギングは「チャネル」に基づいています。各チャネルは、ログ情報を書き込む特定の方法を表します。たとえば、single チャネルはログファイルを 1 つのログファイルに書き込みますが、slack チャネルはログメッセージを Slack に送信します。ログメッセージは、重大度に基づいて複数のチャネルに書き込まれる場合があります。

Laravel は内部で、さまざまな強力なログハンドラーのサポートを提供する Monolog ライブラリを利用します。 Laravel を使用すると、これらのハンドラーの設定が簡単になり、それらを組み合わせてアプリケーションのログ処理をカスタマイズできるようになります。

構成 (Configuration)

アプリケーションのロギング動作を制御するすべての構成オプションは、config/logging.php 構成ファイルに格納されています。このファイルを使用すると、アプリケーションのログチャネルを構成できるため、使用可能な各チャネルとそのオプションを必ず確認してください。以下でいくつかの一般的なオプションを確認します。

デフォルトでは、Laravel はメッセージをログに記録するときに stack チャネルを使用します。 stack チャネルは、複数のログチャネルを 1 つのチャネルに集約するために使用されます。スタックの構築の詳細については、以下のドキュメントを確認してください。

利用可能なチャネルドライバ

各ログチャネルは「ドライバ」によって駆動されます。ドライバは、ログメッセージが実際にどのように、どこに記録されるかを決定します。次のログチャネルドライバは、すべての Laravel アプリケーションで利用できます。これらのドライバのほとんどのエントリはアプリケーションの config/logging.php 構成ファイルにすでに存在しているため、必ずこのファイルを確認してその内容を理解してください。

名前	説明
`custom`	指定されたファクトリを呼び出してチャネルを作成するドライバ。
`daily`	毎日ローテーションする `RotatingFileHandler` ベースの Monolog ドライバ。
`errorlog`	`ErrorLogHandler` ベースの Monolog ドライバ。
`monolog`	サポートされている Monolog ハンドラーを使用できる Monolog ファクトリドライバ。
`papertrail`	`SyslogUdpHandler` ベースの Monolog ドライバ。
`single`	単一のファイルまたはパスベースのロガーチャネル (`StreamHandler`)。
`slack`	`SlackWebhookHandler` ベースの Monolog ドライバ。
`stack`	「マルチチャネル」チャネルの作成を容易にするラッパー。
`syslog`	`SyslogHandler` ベースの Monolog ドライバ。

monolog および custom ドライバの詳細については、高度なチャネルのカスタマイズのドキュメントを参照してください。

チャンネル名の設定

デフォルトでは、Monolog は、production や local など、現在の環境に一致する「チャネル名」でインスタンス化されます。この値を変更するには、チャネルの構成に name オプションを追加します。

'stack' => [
    'driver' => 'stack',
    'name' => 'channel-name',
    'channels' => ['single', 'slack'],
],

チャネルの前提条件

単一チャネルと日次チャネルの構成

single および daily チャネルには、bubble、permission、および locking の 3 つのオプション構成オプションがあります。

名前	説明	デフォルト
`bubble`	メッセージが処理された後に他のチャネルにバブルアップする必要があるかどうかを示します。	`true`
`locking`	ログファイルに書き込む前に、ログファイルをロックしてみてください。	`false`
`permission`	ログファイルの権限。	`0644`

さらに、daily チャネルの保持ポリシーは、LOG_DAILY_DAYS 環境変数を介して、または days 構成オプションを設定することによって構成できます。

名前	説明	デフォルト
`days`	毎日のログファイルを保持する日数。	`14`

Papertrail チャネルの構成

papertrail チャネルには、host および port 構成オプションが必要です。これらは、PAPERTRAIL_URL および PAPERTRAIL_PORT 環境変数を介して定義できます。これらの値は、Papertrail から取得できます。

Slack チャネルの構成

slack チャネルには、url 構成オプションが必要です。この値は、LOG_SLACK_WEBHOOK_URL 環境変数を介して定義できます。この URL は、Slack チーム用に構成した受信 Webhook の URL と一致する必要があります。

デフォルトでは、Slack は critical レベル以上のログのみを受信します。ただし、LOG_LEVEL 環境変数を使用するか、Slack ログチャネルの構成配列内の level 構成オプションを変更することで、これを調整できます。

非推奨の警告のログ記録

PHP、Laravel、およびその他のライブラリは、機能の一部が非推奨になり、将来のバージョンで削除されることをユーザーに通知することがよくあります。これらの非推奨の警告をログに記録したい場合は、LOG_DEPRECATIONS_CHANNEL 環境変数を使用するか、アプリケーションの config/logging.php 構成ファイル内で、優先する deprecations ログチャネルを指定できます。

'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace' => env('LOG_DEPRECATIONS_TRACE', false),
],

'channels' => [
    // ...
]

または、deprecations という名前のログチャネルを定義することもできます。この名前のログチャネルが存在する場合は、非推奨のログを記録するために常に使用されます。

'channels' => [
    'deprecations' => [
        'driver' => 'single',
        'path' => storage_path('logs/php-deprecation-warnings.log'),
    ],
],

ログスタックの構築 (Building Log Stacks)

前述したように、stack ドライバを使用すると、便宜上、複数のチャネルを 1 つのログチャネルに結合できます。ログスタックの使用方法を説明するために、運用アプリケーションで見られる構成例を見てみましょう。

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['syslog', 'slack'], // [tl! add]
        'ignore_exceptions' => false,
    ],

    'syslog' => [
        'driver' => 'syslog',
        'level' => env('LOG_LEVEL', 'debug'),
        'facility' => env('LOG_SYSLOG_FACILITY', LOG_USER),
        'replace_placeholders' => true,
    ],

    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji' => env('LOG_SLACK_EMOJI', ':boom:'),
        'level' => env('LOG_LEVEL', 'critical'),
        'replace_placeholders' => true,
    ],
],

この構成を詳しく見てみましょう。まず、stack チャネルが、channels オプションを介して他の 2 つのチャネル (syslog および slack) を集約していることに注目してください。したがって、メッセージをログに記録する場合、これらのチャネルの両方にメッセージをログに記録する機会があります。ただし、以下で説明するように、これらのチャネルが実際にメッセージをログに記録するかどうかは、メッセージの重大度/「レベル」によって決定される場合があります。

ログレベル

上記の例の syslog および slack チャネル構成に存在する level 構成オプションに注目してください。このオプションは、チャネルによってログに記録されるメッセージの最小「レベル」を決定します。 Laravel のロギングサービスを強化する Monolog は、RFC 5424仕様で定義されたすべてのログレベルを提供します。これらのログレベルは、重大度の降順で、緊急、アラート、重大、エラー、警告*、通知、情報、デバッグです。

そこで、debug メソッドを使用してメッセージをログに記録するとします。

Log::debug('An informational message.');

この構成では、syslog チャネルはメッセージをシステムログに書き込みます。ただし、エラーメッセージはcritical以上ではないため、Slackには送信されません。ただし、emergency メッセージをログに記録すると、emergency レベルが両方のチャネルの最小レベルしきい値を超えているため、メッセージはシステムログと Slack の両方に送信されます。

Log::emergency('The system is down!');

ログメッセージの書き込み (Writing Log Messages)

Log facade を使用して、ログに情報を書き込むことができます。前述したように、ロガーは、RFC 5424仕様で定義された 8 つのログレベル (緊急、アラート、クリティカル、エラー*、警告、通知、情報、デバッグ) を提供します。

use Illuminate\Support\Facades\Log;

Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

これらのメソッドのいずれかを呼び出して、対応するレベルのメッセージをログに記録できます。デフォルトでは、メッセージは、logging 構成ファイルで構成されているデフォルトのログチャネルに書き込まれます。

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     */
    public function show(string $id): View
    {
        Log::info('Showing the user profile for user: {id}', ['id' => $id]);

        return view('user.profile', [
            'user' => User::findOrFail($id)
        ]);
    }
}

コンテキスト情報

コンテキストデータの配列をログメソッドに渡すことができます。このコンテキストデータはフォーマットされて、ログメッセージとともに表示されます。

use Illuminate\Support\Facades\Log;

Log::info('User {id} failed to login.', ['id' => $user->id]);

場合によっては、特定のチャネルの後続のすべてのログエントリに含める必要があるコンテキスト情報を指定したい場合があります。たとえば、アプリケーションへの各受信リクエストに関連付けられたリクエスト ID をログに記録したい場合があります。これを実現するには、Log ファサードの withContext メソッドを呼び出します。

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AssignRequestId
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

        Log::withContext([
            'request-id' => $requestId
        ]);

        $response = $next($request);

        $response->headers->set('Request-Id', $requestId);

        return $response;
    }
}

すべてのロギングチャネル間でコンテキスト情報を共有したい場合は、Log::shareContext() メソッドを呼び出すことができます。このメソッドは、作成されたすべてのチャネルとその後に作成されるチャネルにコンテキスト情報を提供します。

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class AssignRequestId
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

        Log::shareContext([
            'request-id' => $requestId
        ]);

        // ...
    }
}

キューに入れられたジョブの処理中にログコンテキストを共有する必要がある場合は、ジョブミドルウェアを利用できます。

特定のチャネルへの書き込み

場合によっては、アプリケーションのデフォルトチャネル以外のチャネルにメッセージを記録したい場合があります。 Log ファサードで channel メソッドを使用して、構成ファイルで定義されている任意のチャネルを取得してログに記録できます。

use Illuminate\Support\Facades\Log;

Log::channel('slack')->info('Something happened!');

複数のチャネルで構成されるオンデマンドロギングスタックを作成したい場合は、stack メソッドを使用できます。

Log::stack(['single', 'slack'])->info('Something happened!');

オンデマンドチャネル

アプリケーションの logging 構成ファイルにその構成が存在しなくても、実行時に構成を提供することでオンデマンドチャネルを作成することもできます。これを実現するには、構成配列を Log ファサードの build メソッドに渡すことができます。

use Illuminate\Support\Facades\Log;

Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
])->info('Something happened!');

オンデマンドログスタックにオンデマンドチャネルを含めることもできます。これは、stack メソッドに渡される配列にオンデマンドチャネルインスタンスを含めることによって実現できます。

use Illuminate\Support\Facades\Log;

$channel = Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
]);

Log::stack(['slack', $channel])->info('Something happened!');

モノログチャンネルのカスタマイズ (Monolog Channel Customization)

チャンネルのモノログのカスタマイズ

場合によっては、既存のチャネルに対して Monolog を構成する方法を完全に制御する必要がある場合があります。たとえば、Laravel の組み込み single チャネルに対してカスタム Monolog FormatterInterface 実装を構成することができます。

まず、チャネルの構成で tap 配列を定義します。 tap 配列には、Monolog インスタンスの作成後にカスタマイズ (または「利用」) する機会を持つクラスのリストが含まれている必要があります。これらのクラスを配置する従来の場所はないため、アプリケーション内にこれらのクラスを含むディレクトリを自由に作成できます。

'single' => [
    'driver' => 'single',
    'tap' => [App\Logging\CustomizeFormatter::class],
    'path' => storage_path('logs/laravel.log'),
    'level' => env('LOG_LEVEL', 'debug'),
    'replace_placeholders' => true,
],

チャネルで tap オプションを構成したら、Monolog インスタンスをカスタマイズするクラスを定義する準備が整います。このクラスには、Illuminate\Log\Logger インスタンスを受け取る 1 つのメソッド __invoke のみが必要です。 Illuminate\Log\Logger インスタンスは、すべてのメソッド呼び出しを基になる Monolog インスタンスにプロキシします。

<?php

namespace App\Logging;

use Illuminate\Log\Logger;
use Monolog\Formatter\LineFormatter;

class CustomizeFormatter
{
    /**
     * Customize the given logger instance.
     */
    public function __invoke(Logger $logger): void
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(new LineFormatter(
                '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
            ));
        }
    }
}

すべての「タップ」クラスはサービスコンテナによって解決されるため、必要なコンストラクターの依存関係は自動的に挿入されます。

モノログハンドラーチャネルの作成

Monolog にはさまざまな利用可能なハンドラーがあり、Laravel にはそれぞれの組み込みチャネルが含まれていません。場合によっては、対応する Laravel ログドライバを持たない特定の Monolog ハンドラーのインスタンスにすぎないカスタムチャネルを作成したい場合があります。これらのチャネルは、monolog ドライバを使用して簡単に作成できます。

monolog ドライバを使用する場合、handler 構成オプションを使用して、インスタンス化されるハンドラーを指定します。オプションで、ハンドラーに必要なコンストラクターパラメーターは、handler_with 構成オプションを使用して指定できます。

'logentries' => [
    'driver'  => 'monolog',
    'handler' => Monolog\Handler\SyslogUdpHandler::class,
    'handler_with' => [
        'host' => 'my.logentries.internal.datahubhost.company.com',
        'port' => '10000',
    ],
],

モノログフォーマッタ

monolog ドライバを使用する場合、Monolog LineFormatter がデフォルトのフォーマッタとして使用されます。ただし、formatter および formatter_with 構成オプションを使用して、ハンドラーに渡されるフォーマッタのタイプをカスタマイズできます。

'browser' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\BrowserConsoleHandler::class,
    'formatter' => Monolog\Formatter\HtmlFormatter::class,
    'formatter_with' => [
        'dateFormat' => 'Y-m-d',
    ],
],

独自のフォーマッタを提供できる Monolog ハンドラーを使用している場合は、formatter 構成オプションの値を default に設定できます。

'newrelic' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\NewRelicHandler::class,
    'formatter' => 'default',
],

モノログプロセッサ

Monolog は、メッセージをログに記録する前にメッセージを処理することもできます。独自のプロセッサを作成することも、Monolog が提供する既存のプロセッサを使用することもできます。

monolog ドライバのプロセッサーをカスタマイズする場合は、チャネルの構成に processors 構成値を追加します。

'memory' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\StreamHandler::class,
    'handler_with' => [
        'stream' => 'php://stderr',
    ],
    'processors' => [
        // Simple syntax...
        Monolog\Processor\MemoryUsageProcessor::class,

        // With options...
        [
            'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
            'with' => ['removeUsedContextFields' => true],
        ],
    ],
],

ファクトリ経由でカスタムチャネルを作成する

Monolog のインスタンス化と構成を完全に制御できる完全なカスタムチャネルを定義したい場合は、config/logging.php 構成ファイルで custom ドライバタイプを指定できます。構成には、Monolog インスタンスを作成するために呼び出されるファクトリクラスの名前を含む via オプションが含まれている必要があります。

'channels' => [
    'example-custom-channel' => [
        'driver' => 'custom',
        'via' => App\Logging\CreateCustomLogger::class,
    ],
],

custom ドライバチャネルを構成したら、Monolog インスタンスを作成するクラスを定義する準備が整います。このクラスには、Monolog ロガーインスタンスを返す __invoke メソッドが 1 つだけ必要です。このメソッドは、チャネル構成配列を唯一の引数として受け取ります。

<?php

namespace App\Logging;

use Monolog\Logger;

class CreateCustomLogger
{
    /**
     * Create a custom Monolog instance.
     */
    public function __invoke(array $config): Logger
    {
        return new Logger(/* ... */);
    }
}

Pail を使用したログメッセージの追跡 (Tailing Log Messages Using Pail)

多くの場合、アプリケーションのログをリアルタイムで追跡する必要があるかもしれません。たとえば、問題をデバッグする場合や、アプリケーションのログで特定の種類のエラーを監視する場合などです。

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

インストール

Laravel Pail には、PCNTL PHP 拡張機能が必要です。

まず、Composer パッケージマネージャーを使用して Pail をプロジェクトにインストールします。

composer require --dev laravel/pail

使用法

ログの追跡を開始するには、pail コマンドを実行します。

php artisan pail

出力の冗長性を高め、切り捨て (…) を回避するには、-v オプションを使用します。

php artisan pail -v

冗長性を最大限に高め、例外スタックトレースを表示するには、-vv オプションを使用します。

php artisan pail -vv

ログの追跡を停止するには、いつでも Ctrl+C を押してください。

ログのフィルタリング

`--filter`

--filter オプションを使用すると、タイプ、ファイル、メッセージ、スタックトレースの内容によってログをフィルタリングできます。

php artisan pail --filter="QueryException"

`--message`

メッセージのみでログをフィルターするには、--message オプションを使用できます。

php artisan pail --message="User created"

`--level`

--level オプションは、ログレベルでログをフィルタリングするために使用できます。

php artisan pail --level=error

`--user`

特定のユーザーが認証されている間に書き込まれたログのみを表示するには、ユーザーの ID を --user オプションに指定します。

php artisan pail --user=1

導入 (Introduction)​

構成 (Configuration)​

利用可能なチャネルドライバ​

チャンネル名の設定​

チャネルの前提条件​

単一チャネルと日次チャネルの構成​

Papertrail チャネルの構成​

Slack チャネルの構成​

非推奨の警告のログ記録​

ログスタックの構築 (Building Log Stacks)​

ログレベル​

ログメッセージの書き込み (Writing Log Messages)​

コンテキスト情報​

特定のチャネルへの書き込み​

オンデマンドチャネル​

モノログチャンネルのカスタマイズ (Monolog Channel Customization)​

チャンネルのモノログのカスタマイズ​

モノログ ハンドラー チャネルの作成​

モノログ フォーマッタ​

モノログプロセッサ​

ファクトリ経由でカスタム チャネルを作成する​

Pail を使用したログ メッセージの追跡 (Tailing Log Messages Using Pail)​

インストール​

使用法​

ログのフィルタリング​

--filter​

--message​

--level​

--user​

導入 (Introduction)

構成 (Configuration)

利用可能なチャネルドライバ

チャンネル名の設定

チャネルの前提条件

単一チャネルと日次チャネルの構成

Papertrail チャネルの構成

Slack チャネルの構成

非推奨の警告のログ記録

ログスタックの構築 (Building Log Stacks)

ログレベル

ログメッセージの書き込み (Writing Log Messages)

コンテキスト情報

特定のチャネルへの書き込み

オンデマンドチャネル

モノログチャンネルのカスタマイズ (Monolog Channel Customization)

チャンネルのモノログのカスタマイズ

モノログハンドラーチャネルの作成

モノログフォーマッタ

モノログプロセッサ

ファクトリ経由でカスタムチャネルを作成する

Pail を使用したログメッセージの追跡 (Tailing Log Messages Using Pail)

インストール

使用法

ログのフィルタリング

`--filter`

`--message`

`--level`

`--user`