Saltar al contenido principal
Cuando investigas transacciones lentas, no basta con el tiempo de ejecución del SQL. También tienes que revisar el código de la aplicación que se ejecuta dentro de la transacción y el tiempo de espera por bloqueos de la base de datos. En Laravel 13.x, Connection::whenTransactionRunsLongerThan invoca un callback cuando el tiempo total transcurrido de una transacción supera el umbral indicado.
Esta página se basa en la implementación de Laravel Framework 13.x. Comprueba que la versión de Framework que usas incluye este método.

Registrar el callback

Para monitorizar las conexiones de base de datos de toda la aplicación, registra el callback en el método boot de un service provider. El umbral se expresa en milisegundos.
El callback recibe estos tres argumentos.
  • Connection: la conexión de base de datos monitorizada
  • TransactionCommitted|TransactionRolledBack: el evento que indica si la transacción se confirmó (commit) o se revirtió (rollback)
  • float: el tiempo transcurrido medido (en milisegundos)
Si indicas un nombre de conexión, como en DB::connection('mysql'), solo monitorizas esa conexión. Para monitorizar varias conexiones, registra un callback en cada Connection.

Qué se mide

La medición empieza cuando comienza la transacción externa y termina cuando la transacción externa hace commit o rollback.
Laravel guarda la hora de inicio solo cuando el nivel de transacción pasa de 0 a 1. Por eso, aunque una transacción interna funcione como savepoint, su tiempo de procesamiento se incluye en el tiempo transcurrido de la transacción externa. Este mecanismo no sirve para monitorizar una transacción interna con su propio umbral. El callback se llama después de que el nivel de transacción vuelva a 0. Si el callback de DB::transaction lanza una excepción y se hace rollback, también recibes el evento TransactionRolledBack y el tiempo medido. Los mismos eventos se producen cuando llamas manualmente a beginTransaction / commit / rollBack.

Cómo indicar el umbral

Como primer argumento de whenTransactionRunsLongerThan puedes pasar los siguientes tipos. Normalmente basta con indicar los milisegundos directamente. Si prefieres expresarlo en unidades de tiempo, puedes usar CarbonInterval.
La comprobación es si el tiempo transcurrido es mayor que el umbral. Si el tiempo transcurrido es igual al umbral, no se llama al callback. Con un umbral de 0, todas las transacciones medidas activan el callback.

Distinguirlo de la lentitud del SQL

Laravel también ofrece whenQueryingForLongerThan, que monitoriza el tiempo acumulado del SQL ejecutado dentro de una misma petición. Las dos API miden cosas distintas. Si dentro de la transacción llamas a una API externa o hay esperas por bloqueos, el tiempo transcurrido de la transacción puede ser mayor que el tiempo acumulado del SQL. Registrar ambos facilita distinguir si el retraso viene del propio SQL o de otro trabajo dentro de la transacción.

Consideraciones de operación

El callback se llama durante el procesamiento del commit o del rollback, así que limítalo a tareas de monitorización. Puedes escribir logs y registrar métricas, pero no ejecutes escrituras adicionales en la misma conexión ni llamadas externas lentas. Además, si llamas a una API externa dentro de una transacción, su tiempo de espera también se mide. Plantéate si puedes sacar las llamadas externas de la transacción. Esto no solo reduce las alertas, sino que también acorta el tiempo durante el que se mantienen los bloqueos.

Fuentes primarias consultadas

Última modificación el 20 de noviembre de 2026