メインコンテンツへスキップ
トランザクションの遅延を調査するときは、SQLの実行時間だけでなく、トランザクション内で実行されるアプリケーションコードや、データベースのロック待ち時間も確認する必要があります。Laravel 13.xの Connection::whenTransactionRunsLongerThan は、トランザクション全体の経過時間が指定した閾値を超えたときにcallbackを呼び出します。
このページは Laravel Framework 13.xの実装 を元にしています。利用中のFrameworkのバージョンにこのメソッドが含まれていることを確認してください。

callbackを登録する

アプリケーション全体のデータベース接続を監視する場合は、service providerの boot メソッドで登録します。閾値の数値は ミリ秒 です。
callbackには次の3つの引数が渡されます。
  • Connection: 対象のデータベース接続
  • TransactionCommitted|TransactionRolledBack: トランザクションがcommitされたかrollbackされたかを表すevent
  • float: 計測した経過時間(ミリ秒)
DB::connection('mysql') のように接続名を指定すれば、特定の接続だけを監視できます。複数の接続を監視する場合は、それぞれの Connection にcallbackを登録します。

計測される範囲

計測は外側のトランザクションが開始したときに始まり、外側のトランザクションがcommitまたはrollbackされたときに終わります。
Laravelはtransaction levelが 0 から 1 になったときだけ開始時刻を保存します。そのため、内側のtransactionがsavepointとして動作する場合も、内側の処理時間は外側のトランザクションの経過時間に含まれます。内側のtransactionだけを別の閾値で監視する仕組みではありません。 callbackはtransaction levelが 0 に戻った後に呼ばれます。DB::transaction のcallbackが例外を投げてrollbackされた場合も、TransactionRolledBack eventと計測時間を受け取れます。手動で beginTransaction / commit / rollBack を呼び出す場合も同じeventが発生します。

閾値の指定方法

whenTransactionRunsLongerThan の第1引数には、次の形式を渡せます。 通常はミリ秒を直接指定すれば十分です。時間単位で表現したい場合は CarbonInterval を使えます。
判定は「経過時間が閾値より大きいか」で行われます。経過時間が閾値と同じ場合はcallbackは呼ばれません。閾値を 0 にすると、計測できたtransactionがcallbackの対象になります。

SQLの遅延と区別する

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

運用時の注意点

callbackはcommitまたはrollbackの処理中に呼ばれるため、監視用の処理に限定します。ログ出力やmetricsへの記録は行えますが、同じ接続で追加の更新を実行したり、時間のかかる外部通信を行ったりしないでください。 また、トランザクション内で外部APIを呼び出すと、その待ち時間も計測されます。外部通信をトランザクションの外へ移動できないか検討することが、通知を減らすだけでなくロック保持時間の短縮にもつながります。

参照した一次情報

最終更新日 2026年11月20日