Logging

• Introduction
• Configuration
  • Available Channel Drivers
  • Channel Prerequisites
  • Logging Deprecation Warnings
• Building Log Stacks
• Writing Log Messages
  • Contextual Information
  • Writing To Specific Channels
• Monolog Channel Customization
  • Customizing Monolog For Channels
  • Creating Monolog Handler Channels
  • Creating Custom Channels Via Factories

Introduction

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

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

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

Configuration

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

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

Configuring The Channel Name

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

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

Available Channel Drivers

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

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

monolog および custom ドライバの詳細については、advanced channel customization のドキュメントを参照してください。

Channel Prerequisites

Configuring The Single and Daily Channels

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

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

Configuring The Papertrail Channel

papertrail チャネルには、host および port 構成オプションが必要です。これらの値は、Papertrail から取得できます。

Configuring The Slack Channel

slack チャネルには、url 構成オプションが必要です。この URL は、Slack チーム用に構成した incoming webhook の URL と一致する必要があります。

デフォルトでは、Slack は critical レベル以上のログのみを受信します。ただし、Slack ログ チャネルの構成配列内の level 構成オプションを変更することで、config/logging.php 構成ファイルでこれを調整できます。

Logging Deprecation Warnings

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

'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),

'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'],
    ],

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

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

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

Log Levels

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

そこで、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 specification で定義された 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\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Support\Facades\Log;

class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function show($id)
    {
        Log::info('Showing the user profile for user: '.$id);

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

Contextual Information

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

use Illuminate\Support\Facades\Log;

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

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;

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

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

        return $next($request)->header('Request-Id', $requestId);
    }
}

Writing To Specific Channels

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

use Illuminate\Support\Facades\Log;

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

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

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

On-Demand Channels

アプリケーションの 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

Customizing Monolog For Channels

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

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

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

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

<?php

namespace App\Logging;

use Monolog\Formatter\LineFormatter;

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

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

Creating Monolog Handler Channels

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

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

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

Monolog Formatters

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',
],

Creating Custom Channels Via Factories

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.
     *
     * @param  array  $config
     * @return \Monolog\Logger
     */
    public function __invoke(array $config)
    {
        return new Logger(...);
    }
}