Laravel Logを使いこなす方法：基礎から実践まで

バックエンド開発•2025/1/24

皆さんはアプリケーション開発の中で、不意に動作がうまくいかないと感じた経験はないでしょうか。問題の原因を素早く突き止めるために役立つのが、Laravel Log です。 Laravelには強力なロギング機能が標準で備わっていて、コードのどこで何が起きたのかを把握しやすくなります。

しかし、初心者の方にとっては「どこにログが保存されているのか」「どうやってログレベルを切り替えるのか」など、疑問に思うことも多いかもしれません。そこで、ここではLaravel Logの仕組みや設定方法を初心者向けに解説していきます。

また、ロギングの基本を押さえるだけでなく、実務で活用しやすい設定例にも触れます。皆さんが今後Laravelを使って開発を進める際に、「ログってどう書けばいいんだろう？」という不安を感じなくなるように、丁寧に説明します。

Laravelにおけるロギングの基礎

Laravelでは、Monolog をベースにしたロギング機能が標準提供されています。 MonologはPHPのロギングをサポートするライブラリで、さまざまなチャンネルやハンドラを通して多彩なログ出力が可能です。

アプリケーションの挙動を記録することで、不具合の検知や原因究明を行いやすくなります。ログは開発中だけでなく、本番環境でも大きな手助けとなるでしょう。

ログが持つ役割

Laravelのロギングを上手に使うことで、アプリケーションの以下の情報を追跡できます。

予期せぬエラーの内容
APIやバッチ処理などでの実行状況
デバッグや検証のために必要なメッセージ
重要なイベントが発生したタイミング

皆さんが開発を進めるうえで、「エラーが出たときに何が起こったか」を知ることは大切ですね。問題箇所を素早く把握し、適切に対処できるようになることは大きなメリットです。

config/logging.php の役割

Laravelでは、config/logging.php という設定ファイルによってログの動作を細かく制御できます。このファイル内に定義されている channels の項目を調整することで、ログの出力先や形式を変えられます。

たとえば、以下のような設定が含まれています。


'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single'],
        'ignore_exceptions' => false,
    ],

    'single' => [
        'driver' => 'single',
        'path' => storage_path('logs/laravel.log'),
        'level' => env('LOG_LEVEL', 'debug'),
    ],

    // ほかのチャンネル定義
],

stack チャンネルは複数のチャンネルを束ねて扱うドライバです。デフォルトでは single チャンネルを経由して、storage/logs/laravel.log へログを出力するようになっています。

ログレベルを理解する

ログレベルは、ログの重要度を表すために用いられます。 Laravelでは、以下のようなレベルが利用できます。

emergency : システムが使用不能になるような深刻な状態
alert : 即時対応が必要な障害
critical : 致命的な状態
error : 実行時エラー
warning : 潜在的な問題
notice : 正常動作だが注意しておきたい事柄
info : 単なる情報
debug : 開発やデバッグ用の詳細情報

ログレベルを使い分けることで、あとからログを分析するときに目を通すべき情報を絞り込みやすくなります。

簡単なログの書き方

Laravelでログを書きたいときは、以下のように Log ファサードを利用します。


use Illuminate\Support\Facades\Log;

class SampleController extends Controller
{
    public function index()
    {
        Log::info('ページが表示されました。');

        // ほかの処理
    }
}

ここで Log::info() を呼び出すと、infoレベルのログが生成されます。同様に Log::error() や Log::debug() などのメソッドも用意されているので、必要に応じて使い分けると良いでしょう。

ログチャンネルと環境ごとの活用

Laravelのロギングは、.env ファイルで設定されている LOG_CHANNEL によって、どのチャンネルを使うかが切り替わります。本番環境ではdailyログを使いたいけれど、開発環境ではsingleログで十分という場合もありますよね。

single ドライバ

デフォルトの設定でよく利用されるのが single ドライバです。すべてのログが1つのファイル (storage/logs/laravel.log) にまとめられます。シンプルなので初学者の方でも扱いやすいでしょう。

daily ドライバ

daily ドライバを選ぶと、日ごとに別ファイルへログを切り替えて保存します。長期的に運用していると、ログが膨大になることがありますが、dailyを使えばファイルサイズを抑えやすいです。

また、config/logging.php の days パラメータで何日分のログを残すかも指定できます。ログの削除や管理の手間を減らしたい場合に便利ですね。


'daily' => [
    'driver' => 'daily',
    'path' => storage_path('logs/laravel.log'),
    'level' => env('LOG_LEVEL', 'debug'),
    'days' => 14,
],

カスタムチャンネルを使った実務での運用

システム規模が大きくなると、単一のログファイルだけでは管理が難しくなりがちです。たとえば、API呼び出し関連とバッチ処理関連でログを分離したいこともあるでしょう。

カスタムチャンネルの定義

config/logging.php の中に自作のチャンネルを追加します。たとえば、API関連のログを専用に出力したい場合は下記のように設定できます。


'channels' => [
    'api' => [
        'driver' => 'single',
        'path' => storage_path('logs/api.log'),
        'level' => 'info',
    ],

    // ほかのチャンネル定義
],

これで Log::channel ('api') のように呼び出すと、api.log にログが書き込まれるようになります。


Log::channel('api')->info('APIが呼び出されました。');

複数のチャンネルを使い分けることで、ログの分析がしやすくなるでしょう。

ログメッセージの詳細を記録する

ログを単に書くだけではなく、追加の情報も含めたいときがあります。たとえば、ユーザーIDや操作内容などを合わせて記録できると、あとからの解析が便利になりますね。

コンテキストを使ったログ

Laravelの Log ファサードでは、コンテキスト情報を配列で渡すことが可能です。以下の例では、ユーザーIDと操作コマンドをあわせてログに出力しています。


Log::info('ユーザー操作がありました。', [
    'user_id' => 123,
    'action' => 'delete',
]);

ログファイルを見ると、メッセージに続いて {"user_id":123,"action":"delete"} のような情報が表示されます。具体的な情報が増えるほど、原因調査に役立つでしょう。

JSON形式でのログ出力

さらに、Laravelのチャンネル設定で json フォーマットを選べば、ログをJSON形式で取得することも可能です。大量のデータを扱う場合や、外部ツールでの解析を視野に入れる場合は、JSON形式のほうが扱いやすいことがあります。

ログの管理と運用上の注意

プロジェクトが成長するにつれて、ログの量も膨大になります。管理や分析のしやすさを考えながら、いくつかの工夫を取り入れると良いですね。

ログを確認するときは、時間帯やログレベルでフィルタリングすると効率的です。

ログのローテーションと保管

daily ドライバを使っている場合、一定日数を過ぎたら古いログを削除する方法が一般的です。しかし、長期保管が必要なケースでは、外部のストレージやログ管理サービスへの連携を検討することも多いです。

運用の形態によっては、ファイル管理だけではなく、Elasticsearchや他の分析プラットフォームを使って可視化する場合もあります。

エラー通知の自動化

ユーザーに影響を与える深刻なエラーが発生した場合、速やかに気づけることが大切です。ログを監視するツールを導入し、特定のログレベル（例えば error や critical）を検知したらアラートを発報する仕組みも役立ちます。

一方で、同じエラーが大量に発生すると通知が氾濫する可能性もあるため、設定のしきい値や通知先を工夫する必要があります。

例外ハンドリングとの連携

Laravelの例外ハンドラ (app/Exceptions/Handler.php) をカスタマイズすることで、例外発生時にログを出力したり、ユーザーに分かりやすいエラーメッセージを返すことができます。

reportメソッドとrenderメソッド

Handlerクラスには report メソッドと render メソッドが用意されています。 reportでログ出力を行い、renderでユーザー向けのレスポンスを整形することができます。


public function report(Throwable $exception)
{
    Log::error('例外発生', [
        'message' => $exception->getMessage(),
        'line' => $exception->getLine(),
    ]);

    parent::report($exception);
}

public function render($request, Throwable $exception)
{
    return parent::render($request, $exception);
}

このように例外が出たタイミングでログを残せば、発生場所やエラー内容を把握しやすくなります。さらに、運用で必要な情報をコンテキストとして追加しておくと便利ですね。

代表的なエラーログの活用例

実際にエラーログが書き込まれるケースとして、HTTPリクエストの失敗 や データベース接続エラー などが挙げられます。ここではよくある例を取り上げ、どうログを残すと良いかをイメージしてみましょう。

HTTPリクエストの失敗

APIや外部サービスを呼び出すコードで何らかの通信障害が起きた場合、次のようなログ記述が考えられます。


try {
    // 外部API呼び出し
} catch (\Exception $e) {
    Log::error('API呼び出しに失敗しました。', [
        'endpoint' => 'https://example.com/api/v1/',
        'error' => $e->getMessage(),
    ]);
}

endpoint情報を記録しておけば、どのAPIが失敗したのかを素早く知ることができます。

データベース接続エラー

データベースの接続設定が間違っていると、クエリ実行時に例外が投げられます。アプリケーションが複数のDBに接続するような構成の場合、どのDBに対してエラーが起きたかを明示するのがポイントです。


try {
    // データベース操作
} catch (\PDOException $e) {
    Log::critical('DB接続エラー', [
        'database' => 'users_db',
        'error' => $e->getMessage(),
    ]);
}

criticalレベルにしておけば、他のログと明確に区別しやすいですね。

ロギングとセキュリティ

ログには、エラーやアプリケーション情報だけでなく、ユーザーの機密情報 が含まれる可能性があります。そのため、ログに出してはいけない情報や、ログファイルのアクセス制限についても考える必要があります。

パスワードやクレジットカード番号など、機密情報をそのままログに出さないように注意してください。

.envファイルと権限設定

デフォルトでLaravelのログは storage/logs ディレクトリに書き込まれます。このディレクトリを外部からアクセスできないように、サーバーの権限設定やファイアウォール設定を見直しておきましょう。

また、.envファイルにもログレベルやログチャンネルの設定が書かれます。 .envファイルも外部に漏れないように、バージョン管理システムへ誤ってアップロードしないように気をつけてください。

テストしやすいログの書き方

アプリケーション開発では、テストコードを書く場面も増えてきます。ログをテストコードで検証したいときは、モックや偽のチャンネルを活用して確認することが多いです。

fakeメソッドの活用

Laravelの Log ファサードには、テスト用の fake メソッドが用意されています。テスト中だけ実際のログ出力を抑制し、ログに期待したメッセージが存在するかを検証できるので、品質向上に役立ちます。


Log::fake();

$controller = new SampleController();
$controller->index();

Log::assertLogged('info', function ($message) {
    return $message->message === 'ページが表示されました。';
});

このように書くと、テスト実行時にログに出力されるであろう内容を検証できます。

運用を見据えたログ分析

ログは記録するだけでなく、分析や可視化 まで行うことで真価を発揮します。実務では、ログファイルを溜めておくだけでは問題解決までに時間がかかることもあるでしょう。

Logファイルの収集と可視化

大規模なシステムであれば、ログを外部のログ管理サービスへ送る方法が一般的です。例えば、Elastic Stack (Elasticsearch, Logstash, Kibana) を使うことで、リアルタイムに解析が可能になるでしょう。あらゆる条件でフィルタリングや集計ができれば、障害のパターンを洗い出しやすくなります。

アラートの閾値設定

エラー発生が一定回数を超えたときに通知するなど、アラートの閾値をうまく設定すると、必要以上の通知が来ることを防げます。運用担当者が常にログをウォッチするのは大変ですので、ツールを使ってアラートを効率化する工夫もポイントになるでしょう。

よくあるトラブルシューティング

「ログが書き込まれない」場合

storage/logs ディレクトリの書き込み権限を確認する
.envファイルの LOG_CHANNEL が正しく設定されているか確かめる
実行環境と設定ファイルが一致しているかを確認する

「ログレベルが反映されない」場合

.envファイルの LOG_LEVEL 値が適切かをチェックする
キャッシュをクリアしてから再度試す (php artisan config:clearなど)

「特定のチャンネルのログだけ分けたい」場合

config/logging.php にチャンネルを追加して Log::channel ('◯◯') で呼び出す
stackドライバの組み合わせを見直す

トラブルシューティングのときは、まず設定ファイルや.envファイルを再確認することが大事ですね。 Laravelはキャッシュ機能があるため、設定を変えたら適宜キャッシュをクリアするのもお忘れなく。

まとめ

ここまで、Laravel Logの基本から実務での運用例までを紹介しました。ログはアプリケーションの健康状態を示す、大切な情報源です。

初心者の方は、Log ファサードで基本的なログの書き方を覚えるところから始めると良いでしょう。
環境ごとにログチャンネルを切り替えたり、コンテキスト情報を加えたりすることで、ログの分析を効率化できます。
運用するうえでは、日別管理や外部ツールへの連携など、長期的な視点でログを扱う工夫も重要です。

ログはアプリケーション開発者と運用担当者にとって、頼りになる“目”のような存在ではないでしょうか。皆さんもぜひLaravelのロギング機能を上手に活用して、快適な開発・運用環境を整えてみてください。

Laravel Logを使いこなす方法：基礎から実践まで

Laravelにおけるロギングの基礎

ログが持つ役割

config/logging.php の役割

ログレベルを理解する

簡単なログの書き方

ログチャンネルと環境ごとの活用

single ドライバ

daily ドライバ

カスタムチャンネルを使った実務での運用

カスタムチャンネルの定義

ログメッセージの詳細を記録する

コンテキストを使ったログ

JSON形式でのログ出力

ログの管理と運用上の注意

ログのローテーションと保管

エラー通知の自動化

例外ハンドリングとの連携

reportメソッドとrenderメソッド

代表的なエラーログの活用例

HTTPリクエストの失敗

データベース接続エラー

ロギングとセキュリティ

.envファイルと権限設定

テストしやすいログの書き方

fakeメソッドの活用

運用を見据えたログ分析

Logファイルの収集と可視化

アラートの閾値設定

よくあるトラブルシューティング

「ログが書き込まれない」場合

「ログレベルが反映されない」場合

「特定のチャンネルのログだけ分けたい」場合

まとめ

PHPをマスターしよう

バックエンドエンジニアとは？仕事内容・必要スキル・将来性を徹底解説

Laravelにおけるロギングの基礎

ログが持つ役割

config/logging.php の役割

ログレベルを理解する

簡単なログの書き方

ログチャンネルと環境ごとの活用

single ドライバ

daily ドライバ

カスタムチャンネルを使った実務での運用

カスタムチャンネルの定義

ログメッセージの詳細を記録する

コンテキストを使ったログ

JSON形式でのログ出力

ログの管理と運用上の注意

ログのローテーションと保管

エラー通知の自動化

例外ハンドリングとの連携

reportメソッドとrenderメソッド

代表的なエラーログの活用例

HTTPリクエストの失敗

データベース接続エラー

ロギングとセキュリティ

.envファイルと権限設定

テストしやすいログの書き方

fakeメソッドの活用

運用を見据えたログ分析

Logファイルの収集と可視化

アラートの閾値設定

よくあるトラブルシューティング

「ログが書き込まれない」場合

「ログレベルが反映されない」場合

「特定のチャンネルのログだけ分けたい」場合

まとめ

PHPをマスターしよう

バックエンドエンジニア とは？仕事内容・必要スキル・将来性を徹底解説

バックエンドエンジニアとは？仕事内容・必要スキル・将来性を徹底解説