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

# Monitorizar la duración de las transacciones de base de datos

> Aprende a usar Connection::whenTransactionRunsLongerThan en Laravel 13 para detectar transacciones largas al hacer commit o rollback.

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.

> [!NOTE]
>
> Esta página se basa en la [implementación de Laravel Framework 13.x](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php). 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**.

```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,
                ]);
            },
        );
    }
}
```

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.

```php theme={null}
DB::transaction(function () {
    // Aquí empieza la medición

    Order::create($orderData);

    DB::transaction(function () {
        // La transacción interna no se mide por separado
        Inventory::reserve($product);
    });

    // Aquí termina la medición y, si se supera el umbral, se llama al callback
});
```

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.

| Valor | Significado |
| - | - |
| `int` o `float` | Milisegundos |
| `CarbonInterval` | Milisegundos totales del intervalo |
| `DateTimeInterface` | Segundos hasta la hora indicada, convertidos a milisegundos |

Normalmente basta con indicar los milisegundos directamente. Si prefieres expresarlo en unidades de tiempo, puedes usar `CarbonInterval`.

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

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // Registrar logs o métricas de monitorización
    },
);
```

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.

| API | Qué mide | Evento del callback |
| - | - | - |
| `whenQueryingForLongerThan` | Tiempo acumulado de ejecución del SQL dentro de la petición | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | Tiempo transcurrido desde el inicio de la transacción externa hasta su commit o rollback | `TransactionCommitted` o `TransactionRolledBack` |

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

* [Documentación oficial de bases de datos de Laravel](https://github.com/laravel/docs/blob/13.x/database.md)
* [Implementación de `Connection::whenTransactionRunsLongerThan`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Commit que lo añadió a Laravel Framework](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [Temas avanzados](https://kawax.biz/es/advanced/index.md)
- [Configuración de la base de datos](https://kawax.biz/es/database.md)
- [Pruebas de base de datos](https://kawax.biz/es/database-testing.md)
- [Actualización de Laravel — Octubre de 2026](https://kawax.biz/es/blog/changelog/202610.md)
- [Actualización de Laravel 9 a 10](https://kawax.biz/es/blog/upgrade-9-to-10.md)


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