タイムアウト on ララジャパン

クエリの累計時間にタイムアウトを設定する（２）

Thu, 27 Jul 2023 11:10:26 +0900

前回の記事にてタイムアウトとなった場合に２種類の例外がスローされる事を説明しました。クエリ実行中にタイムオーバーとなった場合は、QueryException。クエリ実行外でタイムオーバーとなり、その後クエリを実行してエラーとなる場合は、自作したTimeoutExceptionです。今回はこれらのエラーをどうキャッチしてハンドリングするのか解説します。

検証用のページ

説明の為にテスト用のコントローラを用意しました。

app/Http/Controllers/TimeoutTestController.php

<?php

namespace App\Http\Controllers;

use App\Services\DbQueryTimeout;
use Illuminate\Support\Facades\DB;

class TimeoutTestController extends Controller
{
    public function index()
    {
        $timeout = (int) request('timeout');

        try {
            // 制限時間の指定があればセット
            if ($timeout) {
                DbQueryTimeout::set($timeout);
            }

            // 重いクエリ１
            DB::statement('select sleep(3) union select 1');

            // 重いクエリ２
            DB::statement('select sleep(5) union select 1');

        } catch (\Exception $e) {
            return 'error';
        }

        return 'success';
    }
}

ルーティングは以下の通りです。

routes/web.php

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\TimeoutTestController;

Route::get('/timeout_test', [TimeoutTestController::class, 'index']);

indexアクションでは重いクエリが２つ実行されます。それらが正常に処理できた場合はsuccess、何かしらのエラーが発生した場合はerrorを返します。尚、GETパラメタでtimeoutの指定がある場合は、DbQueryTimeoutを使用して制限時間が設定されます。ビルドインサーバーを起動して挙動を確認してみましょう。

php artisan serv

まず、パラメタ無しで /timeout_test へアクセスしてみてください。約8秒後にsuccessと表示されるはずです。次に、timeoutパラメタを指定して制限時間を設定してみましょう。/timeout_test?timeout=5 として制限時間を5秒にしてアクセスしてみて下さい。すると、約５秒後に処理が中断されerrorと表示されるはずです。

Tips: 重いクエリをシミュレートする方法

重いクエリ = 時間が掛かるクエリ、という事でDB側でsleep()を実行してシミュレートできます。mysqlではsleep()は正常にスリープできた場合は0、途中で中断された場合は1が返却されます。しかし、実際の環境ではmax_execution_timeで指定した時間をオーバーして処理が中断された場合は１ではなくエラーが発生します。sleep()においてもタイムオーバーした場合にエラーを返させるには、unionで追加の処理を実行すればOKです。追加の処理はなんでも良いので今回は適当にselect 1としました。実際にmysql clientにて以下を実行して試してみると理解しやすいと思います。

# 制限時間を5秒に設定
mysql> set max_execution_time = 5000;
Query OK, 0 rows affected (0.01 sec)

# 制限時間内に終わるsleepなら0が返却される
mysql> select sleep(4);
+----------+
| sleep(4) |
+----------+
|        0 |
+----------+
1 row in set (4.05 sec)

# 制限時間内に終わらずsleepが中断されたら1が返却される
mysql> select sleep(5);
+----------+
| sleep(5) |
+----------+
|        1 |
+----------+
1 row in set (5.06 sec)

# unionで追加の処理を含めるとエラーが返却される
mysql> select sleep(6) union select 1;
ERROR 3024 (HY000): Query execution was interrupted, maximum statement execution time exceeded

エラーのハンドリング

冒頭で述べた通り制限時間をオーバーした場合は２種類のタイムアウトエラーが発生します。しかし、アプリにおいては当然それ以外のエラーも発生し得るので、タイムアウトエラーとそうでないエラーの場合で判別してエラーを出し分ける必要があります。それぞれどの様に判別すれば良いでしょうか。

TimeoutExceptionをキャッチ

先に簡単な方から、TimeoutExceptionを判別する場合です。こちらはシンプルにスローされたExceptionのインスタンスをチェックすれば判別できます。TimeoutTestController.php のindexアクションを以下の様に書き換えてみましょう。

app/Http/Controllers/TimeoutTestController.php

...
    public function index()
    {
        $timeout = (int) request('timeout');

        try {
            // 制限時間の指定があればセット
            if ($timeout) {
                DbQueryTimeout::set($timeout);
            }

            // 重いクエリ１
            DB::statement('select sleep(3) union select 1');

            // クエリ以外の処理で3秒掛かった
            sleep(3);

            // 重いクエリ２
            DB::statement('select sleep(5) union select 1');

        } catch (\Exception $e) {
            // TimeoutExceptionの場合のエラー文言
            if ($e instanceof TimeoutException) {
                return 'timeout error';
            }

            return 'error';
        }

        return 'success';
    }

TimeoutExceptionは、クエリ実行外でタイムオーバーし、次のクエリが実行されるタイミングでスローされます。そちらを再現する為に、クエリ１とクエリ２の間にPHP側のスリープを3秒挟みました。これにより制限時間が5秒の場合はTimeoutExceptionがスローされるはずです。再度、ビルドインサーバにて/timeout_test?timeout=5へアクセスしてみて下さい。今度はtimeout errorと表示されたはずです。

クエリ実行中にタイムアウトした場合のエラー

クエリ実行中にタイムアウトした場合はQueryExceptionがスローされます。QueryExceptionはタイムアウト以外でもスローされる例外ですので、前項のTimeoutExceptionの様にインスタンスだけではタイムアウトエラーを判別できません。判別には一歩踏み込んで、$e->errorInfoのチェックが必要です。errorInfoはQueryExceptionの親クラスであるPDOExceptionにセットされていた値で、PHPマニュアルによると、データベースハンドラにおける直近の操作に関連する拡張エラー情報が配列で格納されています。タイムアウトエラーとしてQueryExceptionがスローされた際の$e->errorInfoは以下の様になります。

[
  0 => "HY000"
  1 => 3024
  2 => "Query execution was interrupted, maximum statement execution time exceeded"
]

0はSQLSTATEエラーコード、1はドライバ固有のエラーコード、2はそのエラーメッセージです。判別には1のドライバ固有のエラーコードを使用します。こちらの記事によると、max_execution_timeの設定をオーバーした場合のエラーコードは MySQL 8.0.19 以前は3024か1028で、以降は3024に統一されたとの事です。私の環境はまだMySQL5.7なので、1028のエラーコードも補足する必要があります。これらを考慮して、TimeoutTestControllerの例外処理部分を次の様に修正しました。

app/Http/Controllers/TimeoutTestController.php

...
        } catch (\Exception $e) {
            $timeoutError = false;

            switch (get_class($e)) {
                case TimeoutException::class:
                    $timeoutError = true;
                    break;

                case QueryException::class:
                    if (in_array($e->errorInfo[1], [3024, 1028])) {
                        $timeoutError = true;
                    }
                    break;
            }

            if ($timeoutError) {
                return 'timeout error';
            }

            return 'error';
        }

        return 'success';
    }
}

インスタンスのチェックはswitch文でget_class($e)でクラス名を取得して分岐する様に変更しました。QueryExceptionの場合はerrorInfoでエラーコードもチェックします。クエリ実行中にタイムオーバーとなるように/timeout_test?timeout=7へアクセスしてみて下さい。再度、timeout errorが表示されるはずです。

リファクタリング

これまで説明の為にコントローラ側にタイムアウトエラーのエラー処理のコードを記述してきましたが、DbQueryTimeoutと一緒に色々な箇所で使い回すのでまとめておいた方が良さそうです。という事で、DbQueryTimeout::isTimeoutError()にコードを移しました。

app/Services/DbQueryTimeout.php

...
    // タイムアウトエラー発生？
    public static function isTimeoutError(\Exception $e): bool
    {
        $timeoutError = false;

        switch (get_class($e)) {
            case TimeoutException::class:
                $timeoutError = true;
                break;

            case \Illuminate\Database\QueryException::class:
                if (in_array($e->errorInfo[1], [3024, 1028])) {
                    $timeoutError = true;
                }
                break;
        }

        return $timeoutError;
    }
...

isTimeoutError()はシンプルにタイムアウトエラーか否かを判別するメソッドです。このメソッドを使う事でTimeoutTestController側は次の様にシンプルになりました。

app/Http/Controllers/TimeoutTestController.php

<?php

namespace App\Http\Controllers;

use App\Services\DbQueryTimeout;
use Illuminate\Support\Facades\DB;

class TimeoutTestController extends Controller
{
    public function index()
    {
        $timeout = (int) request('timeout');

        try {
            // 制限時間の指定があればセット
            if ($timeout) {
                DbQueryTimeout::set($timeout);
            }

            // 重いクエリ１
            DB::statement('select sleep(3) union select 1');

            // クエリ以外の処理で3秒掛かった
            sleep(3);

            // 重いクエリ２
            DB::statement('select sleep(5) union select 1');

        } catch (\Exception $e) {
            if (DbQueryTimeout::isTimeoutError($e)) {
                return 'timeout error';
            }

            return 'error';
        }

        return 'success';
    }
}

クエリの累計時間にタイムアウトを設定する（１）

Thu, 27 Jul 2023 11:06:11 +0900

先日、管理サイトにてアラートが発生しました。調査すると、ある検索画面で利用者が重いクエリを連続で発行した事が原因でした。待ち時間が長かった為、不安になり検索ボタンを連打してしまったようです。サーバに負荷を掛ける操作については注意喚起するとして、待ち時間に制限が無いのはよくありません。そこで、検索処理に制限時間を設ける事にしました。今回はそちらの実装にあたって色々学んだことがあるので紹介します。

クエリの実行時間を制限する

今回実装した内容を簡単に説明すると、検索処理に対して実行可能時間を設定し、時間切れとなった場合にエラーを返すというものです、要はタイムアウトの設定です。検索処理においてボトルネックとなっていたのはDBへのクエリ部分で、それ以外の処理時間は無視して良いレベルでした。従って、クエリの実行時間に制限を設ける事にしました。

クエリにタイムアウトを設定する方法については過去の記事の「クエリーの実行所有時間の制限」の項目で紹介されており、今回もこちらを使います。簡単におさらいすると、DB::statement()を使用して、MySQLのmax_execution_timeを設定する方法です。例えば、以下は5秒に制限する場合のコードです。

DB::statement('SET SESSION MAX_EXECUTION_TIME = 5000');

こちらを実行すると、以降クエリで5秒以上掛かった場合にQueryExceptionがスローされます。

クエリの累計時間を制限する

ボトルネックとなるクエリが１つの場合は前項の方法で制限時間を設ければOKですが、今回の実装先には重いクエリが複数実行されており、それらの累計時間を制限する必要がありました。例えば、以下のように制限時間を５秒に設定した場合、クエリ１とクエリ２で合わせて５秒を超えたらタイムアウトエラーとします。

クエリの累計時間に制限を設けるには、クエリを実行する毎に都度残り時間を計算し、それを前項で紹介した方法で設定していけば良さそうです。つまり、以下の様に

クエリ１の時点では残り時間を５秒として制限時間を設定しますが、クエリ２の時点ではクエリ１で３秒掛かったので、残りの実行可能時間２秒を制限時間として再設定します。

DbQueryTimeout.php

ロジックについて理解が深まったところで、実際のコードを紹介します。クエリの制限時間を管理するクラスとして app/Services 配下に DbQueryTimeout.php を追加しました。

app/Services/DbQueryTimeout.php

<?php

namespace App\Services;

use App\Exceptions\TimeoutException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class DbQueryTimeout
{
    const TIMEOUT_QUERY = 'SET SESSION MAX_EXECUTION_TIME';

    public static $maxExecutionTime;  // 最大実行可能時間（ミリ秒）

    public static $processStartTime;  // プロセス開始時刻（マイクロ秒）

    // タイムアウト設定初期化
    public static function set(int $seconds): void
    {
        self::$maxExecutionTime = $seconds * 1000;
        self::$processStartTime = microtime(true);

        DB::beforeExecuting(function ($query) {
            // タイムアウト設定のクエリなら何もしない
            if (Str::startsWith($query, self::TIMEOUT_QUERY)) {
                return;
            }

            // 残りの実行可能時間を計算
            $timeRemaining = self::timeRemaining();

            // 実行可能時間が残っていないなら例外スロー
            if ($timeRemaining <= 0) {
                throw new TimeoutException;
            }

            self::setTimeout($timeRemaining);
        });
    }

    // タイムアウト設定
    public static function setTimeout(int $time): void
    {
        DB::statement(self::TIMEOUT_QUERY.' = '.$time.';');
    }

    // 残りの実行可能時間をミリ秒で返す
    public static function timeRemaining(): int
    {
        return self::$maxExecutionTime - self::elapsedTime();
    }

    // 経過時間をミリ秒で返す
    public static function elapsedTime(): int
    {
        return (int) ((microtime(true) - self::$processStartTime) * 1000);
    }
}

後で説明しますが、このクラス内で使用されている TimeoutException は自作の例外クラスになります。app/Exceptions 配下に TimeoutException.php を追加してください。

app/Exceptions/TimeoutException.php

<?php

namespace App\Exceptions;

use Exception;

class TimeoutException extends Exception
{
}

DbQueryTimeout の使い方はとてもシンプルで、実行時間を制限したい箇所の最初にset()を実行するだけです。set()の引数には制限時間を秒で指定します。例えば、制限時間を５秒としたいなら以下の様に。

DbQueryTimeout::set(5);

すると、set()が実行された時点からカウントダウンが始まり、タイムオーバーとなった場合は以下の２パターンでエラーが発生します。

クエリ実行中
クエリ実行外で、それ以後にクエリを実行しようとした

前者の場合はQueryExceptionがスローされ、後者の場合はTimeoutExceptionがスローされます。

参考までに実装例を掲載します。以下は注文データを検索するページです。

app/Http/Controllers/InvoiceController.php

<?php

namespace App\Http\Controllers;

use App\Models\Invoice;
use App\Models\InvoiceShip;
use Illuminate\Http\Request;
use App\Services\DbQueryTimeout;
use Illuminate\Contracts\View\View;

class InvoiceSearchController extends Controller
{

    /**
     * 検索画面
     */
    public function index(Request $request): View
    {
        $input = $request->all();

        // 制限時間を5秒に設定
        DbQueryTimeout::set(5);

        // 注文データ
        $invoices = Invoice::query()
            ->whereBetween('invoice_date', [$input['date_start'], $input['date_end']])
            ->where('invoice_status', '=', $input['invoice_status'])
            ->orderBy('invoice_date', 'desc')
            ->paginate(config('local.items_per_page'))
            ->withQueryString();

        // 注文配送データ
        $invoice_ships = InvoiceShip::query()
            ->whereIn('invoice_id', $invoices->pluck('invoice_id'))
            ->where('invoice_ship_status', '=', $input['invoice_ship_status'])
            ->get();

        return view('admin.invoice_index')
            ->with(compact('input', 'invoices', 'invoice_ships'));
    }

}

上記のコントローラのindexアクションでは以下の３つのクエリが実行されています。

１ページに表示する注文データ
注文データの件数
注文データに紐づく注文配送データ

これら３つのクエリの累計実行時間が５秒を超える場合はエラーが発生します。エラーが発生した場合の処理については次の投稿で紹介します。

コードのポイント

コア部分であるset()で行われている処理について補足です。set()ではクエリ毎に実行されるbefore処理を登録しています。before処理では以下の処理が実行されます。

実行されるクエリが制限時間の設定クエリなら何もせず、そのまま実行
それ以外のクエリなら残りの実行可能時間を計算
残り時間なし（既にタイムオーバー）ならTimeoutExceptionをスロー
残り時間があるならそれを制限時間として設定

before処理の登録にDB::beforeExecuting()を使用している点がポイントです。こちらはドキュメントには載っていませんが、イベントリスナーの様にEloquentやクエリビルダにてクエリが実行される毎に直前に呼び出すコールバックを登録できます。余談ですが、after処理の登録にはDB::listen()というメソッドがあります。（こちらはドキュメントにも載っている。）

DB::beforeExecuting()のクロージャの引数$queryはSQLが文字列で渡されます。1. 実行されるクエリが制限時間の設定クエリなら何もせず、そのまま実行ではそちらが、SET SESSION MAX_EXECUTION_TIMEから始まるクエリかチェックして、そうならbefore処理を終了しそのままクエリの実行に移ります。そうしなければ、この制限時間を設定するクエリに対しても更にbefore処理をして、、、と無限ループとなってしまうからです。

長くなってしまったので、一旦ここで切ります。次回はエラー処理について解説します。