Passer au contenu principal
Pour analyser des transactions lentes, le temps d’exécution du SQL ne suffit pas. Vous devez aussi examiner le code applicatif exécuté dans la transaction et le temps d’attente des verrous de la base de données. Dans Laravel 13.x, Connection::whenTransactionRunsLongerThan appelle un callback lorsque la durée totale d’une transaction dépasse le seuil indiqué.
Cette page s’appuie sur l’implémentation de Laravel Framework 13.x. Vérifiez que la version du Framework que vous utilisez inclut cette méthode.

Enregistrer le callback

Pour surveiller les connexions de base de données de toute l’application, enregistrez le callback dans la méthode boot d’un service provider. Le seuil est exprimé en millisecondes.
Le callback reçoit les trois arguments suivants.
  • Connection: la connexion de base de données surveillée
  • TransactionCommitted|TransactionRolledBack: l’événement indiquant si la transaction a été validée (commit) ou annulée (rollback)
  • float: la durée mesurée (en millisecondes)
En précisant un nom de connexion, comme DB::connection('mysql'), vous ne surveillez que cette connexion. Pour surveiller plusieurs connexions, enregistrez un callback sur chaque Connection.

Périmètre de la mesure

La mesure commence au démarrage de la transaction externe et se termine lorsque la transaction externe est validée ou annulée.
Laravel n’enregistre l’heure de début que lorsque le niveau de transaction passe de 0 à 1. Ainsi, même lorsqu’une transaction interne fonctionne comme un savepoint, son temps de traitement est inclus dans la durée de la transaction externe. Ce mécanisme ne permet pas de surveiller une transaction interne avec son propre seuil. Le callback est appelé une fois que le niveau de transaction est revenu à 0. Si le callback de DB::transaction lève une exception et que la transaction est annulée, vous recevez aussi l’événement TransactionRolledBack et la durée mesurée. Les mêmes événements sont émis lorsque vous appelez manuellement beginTransaction / commit / rollBack.

Spécifier le seuil

Le premier argument de whenTransactionRunsLongerThan accepte les formes suivantes. En général, indiquer directement des millisecondes suffit. Si vous préférez exprimer le seuil en unités de temps, utilisez CarbonInterval.
Le test vérifie si la durée est strictement supérieure au seuil. Si la durée est égale au seuil, le callback n’est pas appelé. Avec un seuil de 0, chaque transaction mesurée déclenche le callback.

Distinguer d’un SQL lent

Laravel fournit aussi whenQueryingForLongerThan, qui surveille le temps cumulé du SQL exécuté au cours d’une même requête. Les deux API ne mesurent pas la même chose. Si la transaction appelle une API externe ou attend des verrous, sa durée peut dépasser le temps SQL cumulé. En enregistrant les deux, vous distinguez plus facilement un retard dû au SQL lui-même d’un retard dû à un autre traitement dans la transaction.

Points d’attention en production

Le callback est appelé pendant le traitement du commit ou du rollback, limitez-le donc à la surveillance. Vous pouvez écrire des logs et enregistrer des métriques, mais n’effectuez pas d’écritures supplémentaires sur la même connexion ni d’appels externes lents. Par ailleurs, appeler une API externe dans une transaction ajoute aussi son temps d’attente à la mesure. Voyez si vous pouvez sortir les appels externes de la transaction. Cela réduit les alertes et raccourcit aussi la durée de détention des verrous.

Sources primaires consultées

Dernière modification le 20 novembre 2026