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

# Laufzeit von Datenbanktransaktionen überwachen

> Erfahren Sie, wie Sie mit Connection::whenTransactionRunsLongerThan in Laravel 13 lang laufende Transaktionen beim Commit oder Rollback erkennen.

Wenn Sie langsame Transaktionen untersuchen, reicht die Ausführungszeit von SQL allein nicht aus. Sie müssen auch den Anwendungscode innerhalb der Transaktion und die Wartezeit auf Datenbanksperren betrachten. In Laravel 13.x ruft `Connection::whenTransactionRunsLongerThan` einen Callback auf, wenn die gesamte Laufzeit einer Transaktion einen festgelegten Schwellenwert überschreitet.

> [!NOTE]
>
> Diese Seite basiert auf der [Implementierung in Laravel Framework 13.x](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php). Prüfen Sie, ob Ihre Framework-Version diese Methode enthält.

## Callback registrieren

Um die Datenbankverbindungen der gesamten Anwendung zu überwachen, registrieren Sie den Callback in der `boot`-Methode eines Service Providers. Der Schwellenwert wird in **Millisekunden** angegeben.

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

Der Callback erhält drei Argumente.

* `Connection`: die überwachte Datenbankverbindung
* `TransactionCommitted|TransactionRolledBack`: das Event, das angibt, ob die Transaktion committet oder zurückgerollt wurde
* `float`: die gemessene Laufzeit (in Millisekunden)

Wenn Sie einen Verbindungsnamen angeben, etwa `DB::connection('mysql')`, überwachen Sie nur diese Verbindung. Um mehrere Verbindungen zu überwachen, registrieren Sie für jede `Connection` einen Callback.

## Gemessener Bereich

Die Messung beginnt, wenn die äußere Transaktion startet, und endet, wenn die äußere Transaktion committet oder zurückgerollt wird.

```php theme={null}
DB::transaction(function () {
    // Hier beginnt die Messung

    Order::create($orderData);

    DB::transaction(function () {
        // Die innere Transaktion wird nicht separat gemessen
        Inventory::reserve($product);
    });

    // Hier endet die Messung; bei Überschreitung des Schwellenwerts wird der Callback aufgerufen
});
```

Laravel speichert die Startzeit nur, wenn der Transaction Level von `0` auf `1` steigt. Auch wenn eine innere Transaktion als Savepoint läuft, ist ihre Verarbeitungszeit daher in der Laufzeit der äußeren Transaktion enthalten. Mit diesem Mechanismus lässt sich eine innere Transaktion nicht mit einem eigenen Schwellenwert überwachen.

Der Callback wird aufgerufen, nachdem der Transaction Level wieder `0` ist. Wenn der Callback von `DB::transaction` eine Exception wirft und die Transaktion zurückgerollt wird, erhalten Sie ebenfalls das Event `TransactionRolledBack` und die gemessene Zeit. Dieselben Events treten auch auf, wenn Sie `beginTransaction` / `commit` / `rollBack` manuell aufrufen.

## Schwellenwert angeben

Als erstes Argument von `whenTransactionRunsLongerThan` können Sie folgende Formen übergeben.

| Wert | Bedeutung |
| - | - |
| `int` oder `float` | Millisekunden |
| `CarbonInterval` | Gesamtzahl der Millisekunden des Intervalls |
| `DateTimeInterface` | Sekunden bis zum angegebenen Zeitpunkt, in Millisekunden umgerechnet |

In der Regel genügt es, Millisekunden direkt anzugeben. Wenn Sie den Wert lieber in Zeiteinheiten ausdrücken, können Sie `CarbonInterval` verwenden.

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

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // Logs oder Metriken für das Monitoring erfassen
    },
);
```

Geprüft wird, ob die Laufzeit größer als der Schwellenwert ist. Ist die Laufzeit genau gleich dem Schwellenwert, wird der Callback nicht aufgerufen. Bei einem Schwellenwert von `0` löst jede gemessene Transaktion den Callback aus.

## Von langsamem SQL unterscheiden

Laravel bietet außerdem `whenQueryingForLongerThan`, das die kumulierte Zeit der innerhalb eines Requests ausgeführten SQL-Abfragen überwacht. Die beiden APIs messen unterschiedliche Dinge.

| API | Gemessen wird | Event im Callback |
| - | - | - |
| `whenQueryingForLongerThan` | Kumulierte SQL-Ausführungszeit innerhalb des Requests | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | Laufzeit vom Start der äußeren Transaktion bis zu Commit oder Rollback | `TransactionCommitted` oder `TransactionRolledBack` |

Wenn innerhalb einer Transaktion externe APIs aufgerufen werden oder auf Sperren gewartet wird, kann die Laufzeit der Transaktion größer sein als die kumulierte SQL-Zeit. Wenn Sie beides erfassen, können Sie leichter unterscheiden, ob eine Verzögerung vom SQL selbst oder von anderer Arbeit innerhalb der Transaktion stammt.

## Hinweise für den Betrieb

Der Callback wird während der Verarbeitung von Commit oder Rollback aufgerufen. Beschränken Sie ihn daher auf Monitoring. Logs und Metriken sind in Ordnung, aber führen Sie keine weiteren Schreibvorgänge über dieselbe Verbindung und keine langsamen externen Aufrufe aus.

Wenn Sie innerhalb einer Transaktion externe APIs aufrufen, wird auch deren Wartezeit mitgemessen. Prüfen Sie, ob Sie externe Aufrufe aus der Transaktion herausverlagern können. Das reduziert nicht nur Benachrichtigungen, sondern verkürzt auch die Dauer, in der Sperren gehalten werden.

## Verwendete Primärquellen

* [Offizielle Laravel-Datenbankdokumentation](https://github.com/laravel/docs/blob/13.x/database.md)
* [Implementierung von `Connection::whenTransactionRunsLongerThan`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Commit, mit dem die Methode zu Laravel Framework hinzugefügt wurde](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [Weiterführende Themen](https://kawax.biz/de/advanced/index.md)
- [Vorstellung von Laravel Wayfinder](https://kawax.biz/de/blog/wayfinder-introduction.md)
- [Ausführungssteuerung von Queue-Jobs](https://kawax.biz/de/advanced/queue-job-control.md)
- [Artisan-Befehle in Paketen registrieren und Abhängigkeiten auflösen](https://kawax.biz/de/advanced/package-commands.md)
- [Benutzerdefinierte Agenten](https://kawax.biz/de/packages/laravel-copilot-sdk/custom-agents.md)


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