Vai al contenuto principale
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.
Questa pagina si basa sull’implementazione di Laravel Framework 13.x. 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.
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.
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. Di solito è sufficiente indicare direttamente i millisecondi. Se preferisci esprimere la soglia in unità di tempo, puoi usare CarbonInterval.
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. 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

Ultima modifica il 20 novembre 2026