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

# Surveiller la durée des transactions de base de données

> Découvrez comment utiliser Connection::whenTransactionRunsLongerThan dans Laravel 13 pour détecter les transactions longues lors du commit ou du rollback.

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é.

> [!NOTE]
>
> Cette page s'appuie sur l'[implémentation de Laravel Framework 13.x](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php). 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**.

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

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.

```php theme={null}
DB::transaction(function () {
    // La mesure commence ici

    Order::create($orderData);

    DB::transaction(function () {
        // La transaction interne n'est pas mesurée séparément
        Inventory::reserve($product);
    });

    // La mesure se termine ici et le callback est appelé si le seuil est dépassé
});
```

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.

| Valeur | Signification |
| - | - |
| `int` ou `float` | Millisecondes |
| `CarbonInterval` | Nombre total de millisecondes de l'intervalle |
| `DateTimeInterface` | Secondes jusqu'à l'instant indiqué, converties en millisecondes |

En général, indiquer directement des millisecondes suffit. Si vous préférez exprimer le seuil en unités de temps, utilisez `CarbonInterval`.

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

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // Enregistrer des logs ou des métriques de surveillance
    },
);
```

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.

| API | Ce qui est mesuré | Événement du callback |
| - | - | - |
| `whenQueryingForLongerThan` | Temps d'exécution SQL cumulé au cours de la requête | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | Durée entre le début de la transaction externe et son commit ou rollback | `TransactionCommitted` ou `TransactionRolledBack` |

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

* [Documentation officielle de Laravel sur les bases de données](https://github.com/laravel/docs/blob/13.x/database.md)
* [Implémentation de `Connection::whenTransactionRunsLongerThan`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Commit qui l'a ajoutée à Laravel Framework](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [Sujets avancés](https://kawax.biz/fr/advanced/index.md)
- [Configuration de la base de données](https://kawax.biz/fr/database.md)
- [Extension des connexions de base de données pour les packages](https://kawax.biz/fr/advanced/package-database-connections.md)
- [Mise à niveau de Laravel 9 vers 10](https://kawax.biz/fr/blog/upgrade-9-to-10.md)
- [Stores de cache personnalisés et contrats pour les packages](https://kawax.biz/fr/advanced/package-cache-drivers.md)


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