Laravel 6.x ログ

イントロダクション

アプリケーションで発生している事象を確実に捕らえるため、Laravelはログメッセージをファイルやシステムエラーログ、さらにチーム全体に知らせるためのSlack通知も可能な、堅牢なログサービスを提供しています。

そのために、Laravelは多くのパワフルなログハンドラをサポートしている、Monologライブラリーを活用しています。Laravelはそうしたハンドラの設定を簡単にできるようにし、アプリケーションのログ処理に合わせカスタマイズするため、ハンドラを多重に使ったり、マッチングできるようにしています。

設定

アプリケーションのログシステムの設定はすべて、config/logging.php設定ファイルに用意されています。このファイルはアプリケーションのログチャンネルを設定できるため、使用可能なチャンネルやその他のオプションをしっかりとレビューしてください。よく使用されるオプションを以降からレビューします。

デフォルトでは、Laravelはstackチャンネルをメッセージをログする場合に使用します。stackチャンネルは、複数のログチャンネルを一つのログチャンネルへ集結するために使用します。スタックの構築に関する詳細は、このドキュメントで後ほど説明します。

チャンネル名の設定

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

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

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

Tip!! monologとcustomドライバの詳細は、上級チャンネルカスタマイズのドキュメントを確認し、学んでください。

シングルファイルとディリーチャンネルの設定

singleとdailyチャンネルは３つ設定オプションを持っています。bubble、permission、lockingです。

Papertrailチャンネルの設置

papertrailチャンネルでは、urlとport設定オプションが必要です。Papertrailから、それらの値を入手できます。

Slackチャンネルの設定

slackチャンネルには、url設定オプションが必須です。このURLはSlackチームに対して設定されている、incoming webhookへのURLと一致させる必要があります。デフォルトでSlackはcriticalレベル以上のログのみを受け付けます。しかしながら、logging設定ファイルでこれを調整可能です。

ログスタックの構築

先に説明した通り、stackドライバーは、複数のチャンネルを一つのログチャンネルへまとめるために使用します。ログスタックの使用方法を説明するため、ある実働環境に対する設定例を見てみましょう。

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['syslog', 'slack'],
    ],

    'syslog' => [
        'driver' => 'syslog',
        'level' => 'debug',
    ],

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

では、個別にこの設定を確認しましょう。最初に、stackチャンネルがchannelsオプションによりsyslogとslack、２つのチャンネルをまとめていることに注目してください。

ログレベル

上記の例で、syslogとslackチャンネル設定の中に、level設定オプションが存在していることに注目です。このオプションは、そのチャンネルでメッセージをログする、最低の「レベル」を定めるオプションです。Laravelのログサービスを動かしているMonologは、RFC 5424規約で定められている全ログレベルが使用できます。emergencyとalert、critical、error、warning、notice、info、debugです。

debugメソッドを使用し、メッセージをログしてみることを想像しましょう。

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

上記設定では、syslogチャンネルにより、システムログへメッセージを書き込みます。しかしながら、エラーメッセージはcritical以上ではないため、Slackには送られません。ところが、emergencyメッセージをログする場合、両方のチャンネルに対する最低の基準レベル以上のため、システムログとSlackの両方へ送られます。

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

ログメッセージの記述

Logファサードを使い、情報をログできます。先に説明したように、ロガーはRFC 5424規約に定義されている、emergency、alert、critical、error、warning、notice、info、debugの８ログレベルを提供しています。

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

ログメッセージレベルに応じたメソッドを呼び出してください。デフォルトでは、config/logging.php設定ファイルで定義されているデフォルトログチャンネルへ、メッセージが書き込まれます。

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\User;
use Illuminate\Support\Facades\Log;

class UserController extends Controller
{
    /**
     * 指定したユーザーのプロファイルを表示
     *
     * @param  int  $id
     * @return Response
     */
    public function showProfile($id)
    {
        Log::info('Showing user profile for user: '.$id);

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

文脈情報

ログメソッドには、文脈情報の配列を渡すことも可能です。この文脈情報は、ログメッセージに整形され、表示されます。

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

指定チャンネルへの記述

アプリケーションのデフォルトチャンネルの代わりに、別のチャンネルへメッセージをログしたい場合もあります。設定ファイルに定義してあるチャンネルをLogファサードのchannelメソッドを使い取得し、ログしてください。

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

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

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

Monologチャンネルの上級カスタマイズ

チャンネル用Monologカスタマイズ

既存チャンネルに対するMonologの設定方法を複雑にコントロールする必要がある場合もあり得ます。たとえば、指定したチャンネルハンドラに対し、MonologのFormatterInterfaceカスタム実装を設定したい場合です。

そのためには、チャンネルの設定で、tap配列を定義します。tap配列は、生成された後のMonologインスタンスをカスタマイズ（もしくは利用 : "tap into"）する機会を与える、クラスのリストを含んでいる必要があります。

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

チャンネルに対するtapオプションを定義したら、Monologインスタンスをカスタマイズするクラスを定義する準備が整いました。このクラスはIlluminate\Log\Loggerインスタンスを受け取る、__invokeメソッドのみ必要です。Illuminate\Log\Loggerインスタンスは、すべてのメソッドを裏で動作するMonologインスタンスへ送るプロキシクラスです。

<?php

namespace App\Logging;

class CustomizeFormatter
{
    /**
     * 渡されたロガーインスタンスのカスタマイズ
     *
     * @param  \Illuminate\Log\Logger  $logger
     * @return void
     */
    public function __invoke($logger)
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(...);
        }
    }
}

Tip!! すべての"tap"クラスは、サービスコンテナにより、依存解決されます。そのため、コンストラクタで要求した依存は、自動的に注入されます。

Monologハンドラチャンネルの作成

Monologはバラエティーに富んだ利用可能なハンドラを用意しています。あるケースでは、生成したいロガーのタイプが、単に特定のハンドラを持つMonologドライバであることがあります。こうしたチャンネルはmonologドライバーを使用し、生成できます。

monologドライバーを使用する場合、インスタンス化するハンドラを指定するために、handler設定オプションを使います。任意のコンストラクタパラメータを指定する必要がある場合は、with設定オプションを使用します。

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

Monologフォーマッター

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のインスタンス化と設定を完全にコントロールするために、完全なカスタムチャンネルを定義したい場合は、config/logging.php設定ファイルで、customドライバータイプを指定してください。Monologインスンタンスを生成するために、呼び出すファクトリクラスを指定するために、viaオプションを設定に含める必要があります。

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

customチャンネルを設定したら、Monologインスタンスを生成するクラスを定義する準備が整いました。このクラスはMonologインスタンスを返す、__invokeメソッドのみ必要です。

<?php

namespace App\Logging;

use Monolog\Logger;

class CreateCustomLogger
{
    /**
     * カスタムMonologインスタンスの生成
     *
     * @param  array  $config
     * @return \Monolog\Logger
     */
    public function __invoke(array $config)
    {
        return new Logger(...);
    }
}