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

# Monitorare la durata delle transazioni del database

> Scopri come usare Connection::whenTransactionRunsLongerThan in Laravel 13 per rilevare le transazioni lunghe al momento del commit o del rollback.

Quando analizzi transazioni lente, il tempo di esecuzione dell'SQL non basta. Devi considerare anche il codice applicativo eseguito all'interno della transazione e il tempo di attesa sui lock del database. In Laravel 13.x, `Connection::whenTransactionRunsLongerThan` invoca un callback quando la durata complessiva di una transazione supera la soglia indicata.

> [!NOTE]
>
> Questa pagina si basa sull'[implementazione di Laravel Framework 13.x](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php). Verifica che la versione del Framework che usi includa questo metodo.

## Registrare il callback

Per monitorare le connessioni al database di tutta l'applicazione, registra il callback nel metodo `boot` di un service provider. La soglia è espressa in **millisecondi**.

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

Il callback riceve tre argomenti.

* `Connection`: la connessione al database monitorata
* `TransactionCommitted|TransactionRolledBack`: l'evento che indica se la transazione è stata confermata (commit) o annullata (rollback)
* `float`: il tempo trascorso misurato (in millisecondi)

Indicando il nome di una connessione, come in `DB::connection('mysql')`, monitori solo quella connessione. Per monitorare più connessioni, registra un callback su ciascuna `Connection`.

## Cosa viene misurato

La misurazione inizia quando parte la transazione esterna e termina quando la transazione esterna esegue il commit o il rollback.

```php theme={null}
DB::transaction(function () {
    // Qui inizia la misurazione

    Order::create($orderData);

    DB::transaction(function () {
        // La transazione interna non viene misurata separatamente
        Inventory::reserve($product);
    });

    // Qui termina la misurazione e, se la soglia è superata, viene chiamato il callback
});
```

Laravel salva l'orario di inizio solo quando il livello di transazione passa da `0` a `1`. Per questo, anche quando una transazione interna funziona come savepoint, il suo tempo di elaborazione rientra nella durata della transazione esterna. Questo meccanismo non permette di monitorare una transazione interna con una soglia propria.

Il callback viene chiamato dopo che il livello di transazione è tornato a `0`. Se il callback di `DB::transaction` lancia un'eccezione e la transazione viene annullata, ricevi comunque l'evento `TransactionRolledBack` e il tempo misurato. Gli stessi eventi vengono emessi anche quando chiami manualmente `beginTransaction` / `commit` / `rollBack`.

## Come specificare la soglia

Come primo argomento di `whenTransactionRunsLongerThan` puoi passare i seguenti tipi.

| Valore | Significato |
| - | - |
| `int` o `float` | Millisecondi |
| `CarbonInterval` | Millisecondi totali dell'intervallo |
| `DateTimeInterface` | Secondi fino all'istante indicato, convertiti in millisecondi |

Di solito è sufficiente indicare direttamente i millisecondi. Se preferisci esprimere la soglia in unità di tempo, puoi usare `CarbonInterval`.

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

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // Registra log o metriche di monitoraggio
    },
);
```

Il controllo verifica se il tempo trascorso è maggiore della soglia. Se il tempo trascorso è uguale alla soglia, il callback non viene chiamato. Con una soglia di `0`, ogni transazione misurata attiva il callback.

## Distinguerlo dall'SQL lento

Laravel offre anche `whenQueryingForLongerThan`, che monitora il tempo cumulativo dell'SQL eseguito all'interno di una singola richiesta. Le due API misurano cose diverse.

| API | Cosa misura | Evento del callback |
| - | - | - |
| `whenQueryingForLongerThan` | Tempo cumulativo di esecuzione SQL nella richiesta | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | Tempo trascorso dall'inizio della transazione esterna al commit o al rollback | `TransactionCommitted` o `TransactionRolledBack` |

Se all'interno della transazione chiami un'API esterna o si verificano attese sui lock, la durata della transazione può superare il tempo SQL cumulativo. Registrando entrambi, è più facile capire se il ritardo dipende dall'SQL stesso o da altre operazioni all'interno della transazione.

## Note operative

Il callback viene chiamato durante l'elaborazione del commit o del rollback, quindi limitalo al monitoraggio. Puoi scrivere log e registrare metriche, ma non eseguire scritture aggiuntive sulla stessa connessione né chiamate esterne lente.

Inoltre, se chiami un'API esterna all'interno di una transazione, anche il suo tempo di attesa viene misurato. Valuta se puoi spostare le chiamate esterne fuori dalla transazione. Così riduci le notifiche e accorci anche il tempo per cui vengono mantenuti i lock.

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel sul database](https://github.com/laravel/docs/blob/13.x/database.md)
* [Implementazione di `Connection::whenTransactionRunsLongerThan`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Commit che l'ha aggiunta a Laravel Framework](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [Argomenti avanzati](https://kawax.biz/it/advanced/index.md)
- [Estendere le connessioni al database nei pacchetti](https://kawax.biz/it/advanced/package-database-connections.md)
- [Test del database](https://kawax.biz/it/database-testing.md)
- [Gestire i fallimenti delle migrazioni con l'evento MigrationFailed](https://kawax.biz/it/advanced/migration-failed-event.md)
- [Configurazione del database](https://kawax.biz/it/database.md)


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