> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# データベーストランザクションの実行時間を監視する

> Laravel 13のConnection::whenTransactionRunsLongerThanで、長時間トランザクションをコミット・ロールバック時に検出する方法を解説します。

トランザクションの遅延を調査するときは、SQLの実行時間だけでなく、トランザクション内で実行されるアプリケーションコードや、データベースのロック待ち時間も確認する必要があります。Laravel 13.xの `Connection::whenTransactionRunsLongerThan` は、トランザクション全体の経過時間が指定した閾値を超えたときにcallbackを呼び出します。

> [!NOTE]
>
> このページは [Laravel Framework 13.xの実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php) を元にしています。利用中のFrameworkのバージョンにこのメソッドが含まれていることを確認してください。

## callbackを登録する

アプリケーション全体のデータベース接続を監視する場合は、service providerの `boot` メソッドで登録します。閾値の数値は **ミリ秒** です。

```php theme={null}
<?php

namespace App\Providers;

use Illuminate\Database\Connection;
use Illuminate\Database\Events\TransactionCommitted;
use Illuminate\Database\Events\TransactionRolledBack;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        DB::connection()->whenTransactionRunsLongerThan(
            500,
            function (
                Connection $connection,
                TransactionCommitted|TransactionRolledBack $event,
                float $duration,
            ): void {
                Log::warning('Long database transaction detected.', [
                    'connection' => $connection->getName(),
                    'duration_ms' => $duration,
                    'event' => $event::class,
                ]);
            },
        );
    }
}
```

callbackには次の3つの引数が渡されます。

* `Connection`: 対象のデータベース接続
* `TransactionCommitted|TransactionRolledBack`: トランザクションがcommitされたかrollbackされたかを表すevent
* `float`: 計測した経過時間（ミリ秒）

`DB::connection('mysql')` のように接続名を指定すれば、特定の接続だけを監視できます。複数の接続を監視する場合は、それぞれの `Connection` にcallbackを登録します。

## 計測される範囲

計測は外側のトランザクションが開始したときに始まり、外側のトランザクションがcommitまたはrollbackされたときに終わります。

```php theme={null}
DB::transaction(function () {
    // ここから計測が始まる

    Order::create($orderData);

    DB::transaction(function () {
        // 内側のtransactionは個別には計測されない
        Inventory::reserve($product);
    });

    // ここで計測が終わり、閾値を超えていればcallbackが呼ばれる
});
```

Laravelはtransaction levelが `0` から `1` になったときだけ開始時刻を保存します。そのため、内側のtransactionがsavepointとして動作する場合も、内側の処理時間は外側のトランザクションの経過時間に含まれます。内側のtransactionだけを別の閾値で監視する仕組みではありません。

callbackはtransaction levelが `0` に戻った後に呼ばれます。`DB::transaction` のcallbackが例外を投げてrollbackされた場合も、`TransactionRolledBack` eventと計測時間を受け取れます。手動で `beginTransaction` / `commit` / `rollBack` を呼び出す場合も同じeventが発生します。

## 閾値の指定方法

`whenTransactionRunsLongerThan` の第1引数には、次の形式を渡せます。

| 値 | 意味 |
| - | - |
| `int` または `float` | ミリ秒 |
| `CarbonInterval` | intervalの合計ミリ秒 |
| `DateTimeInterface` | 指定時刻までの秒数をミリ秒に変換した値 |

通常はミリ秒を直接指定すれば十分です。時間単位で表現したい場合は `CarbonInterval` を使えます。

```php theme={null}
use Carbon\CarbonInterval;
use Illuminate\Support\Facades\DB;

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // 監視用のログやmetricsを記録する
    },
);
```

判定は「経過時間が閾値より大きいか」で行われます。経過時間が閾値と同じ場合はcallbackは呼ばれません。閾値を `0` にすると、計測できたtransactionがcallbackの対象になります。

## SQLの遅延と区別する

Laravelには、1回のrequest内で実行したSQLの累積時間を監視する `whenQueryingForLongerThan` もあります。2つのAPIは計測対象が異なります。

| API | 計測対象 | callbackのevent |
| - | - | - |
| `whenQueryingForLongerThan` | request内のSQL実行時間の累積 | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | 外側のtransaction開始からcommitまたはrollbackまでの経過時間 | `TransactionCommitted` または `TransactionRolledBack` |

トランザクション内で外部APIを呼び出していたり、ロック待ちが発生していたりすると、SQLの累積時間よりトランザクションの経過時間のほうが大きくなることがあります。両方を記録すると、遅延がSQLそのものによるものか、トランザクション内の別の処理によるものかを切り分けやすくなります。

## 運用時の注意点

callbackはcommitまたはrollbackの処理中に呼ばれるため、監視用の処理に限定します。ログ出力やmetricsへの記録は行えますが、同じ接続で追加の更新を実行したり、時間のかかる外部通信を行ったりしないでください。

また、トランザクション内で外部APIを呼び出すと、その待ち時間も計測されます。外部通信をトランザクションの外へ移動できないか検討することが、通知を減らすだけでなくロック保持時間の短縮にもつながります。

## 参照した一次情報

* [Laravel公式データベースドキュメント](https://github.com/laravel/docs/blob/13.x/database.md)
* [`Connection::whenTransactionRunsLongerThan` の実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Laravel Frameworkへの追加コミット](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [応用トピック](https://kawax.biz/jp/advanced/index.md)
- [Eloquent Observers とモデルイベント](https://kawax.biz/jp/advanced/eloquent-observers.md)
- [イベントとリスナー](https://kawax.biz/jp/events.md)
- [Pest PHPで始めるLaravelテスト](https://kawax.biz/jp/blog/pest-introduction.md)
- [データベーステスト](https://kawax.biz/jp/database-testing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.