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

# 데이터베이스 트랜잭션 실행 시간 모니터링하기

> Laravel 13의 Connection::whenTransactionRunsLongerThan으로 오래 걸리는 트랜잭션을 커밋·롤백 시점에 감지하는 방법을 설명합니다.

트랜잭션 지연을 조사할 때는 SQL 실행 시간뿐 아니라 트랜잭션 안에서 실행되는 애플리케이션 코드와 데이터베이스 락 대기 시간도 확인해야 합니다. Laravel 13.x의 `Connection::whenTransactionRunsLongerThan`은 트랜잭션 전체의 경과 시간이 지정한 임계값을 넘으면 callback을 호출합니다.

> [!NOTE]
>
> 이 페이지는 [Laravel Framework 13.x 구현](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)을 바탕으로 합니다. 사용 중인 Framework 버전에 이 메서드가 포함되어 있는지 확인하세요.

## callback 등록하기

애플리케이션 전체의 데이터베이스 연결을 모니터링하려면 service provider의 `boot` 메서드에서 등록합니다. 임계값의 단위는 **밀리초**입니다.

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

callback에는 다음 세 개의 인수가 전달됩니다.

* `Connection`: 대상 데이터베이스 연결
* `TransactionCommitted|TransactionRolledBack`: 트랜잭션이 commit되었는지 rollback되었는지를 나타내는 event
* `float`: 측정한 경과 시간(밀리초)

`DB::connection('mysql')`처럼 연결 이름을 지정하면 특정 연결만 모니터링할 수 있습니다. 여러 연결을 모니터링하려면 각 `Connection`에 callback을 등록합니다.

## 측정 범위

측정은 바깥쪽 트랜잭션이 시작될 때 시작되고, 바깥쪽 트랜잭션이 commit 또는 rollback될 때 끝납니다.

```php theme={null}
DB::transaction(function () {
    // 여기서 측정이 시작된다

    Order::create($orderData);

    DB::transaction(function () {
        // 안쪽 transaction은 개별적으로 측정되지 않는다
        Inventory::reserve($product);
    });

    // 여기서 측정이 끝나고, 임계값을 넘었으면 callback이 호출된다
});
```

Laravel은 transaction level이 `0`에서 `1`이 될 때만 시작 시각을 저장합니다. 따라서 안쪽 transaction이 savepoint로 동작하는 경우에도 안쪽 처리 시간은 바깥쪽 트랜잭션의 경과 시간에 포함됩니다. 안쪽 transaction만 별도의 임계값으로 모니터링하는 구조는 아닙니다.

callback은 transaction level이 `0`으로 돌아간 뒤에 호출됩니다. `DB::transaction`의 callback이 예외를 던져 rollback된 경우에도 `TransactionRolledBack` event와 측정 시간을 받을 수 있습니다. `beginTransaction` / `commit` / `rollBack`을 수동으로 호출하는 경우에도 같은 event가 발생합니다.

## 임계값 지정 방법

`whenTransactionRunsLongerThan`의 첫 번째 인수에는 다음 형식을 전달할 수 있습니다.

| 값 | 의미 |
| - | - |
| `int` 또는 `float` | 밀리초 |
| `CarbonInterval` | interval의 총 밀리초 |
| `DateTimeInterface` | 지정한 시각까지의 초를 밀리초로 변환한 값 |

보통은 밀리초를 직접 지정하면 충분합니다. 시간 단위로 표현하고 싶다면 `CarbonInterval`을 사용할 수 있습니다.

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

DB::connection()->whenTransactionRunsLongerThan(
    CarbonInterval::seconds(1),
    static function (): void {
        // 모니터링용 로그나 metrics를 기록한다
    },
);
```

판정은 "경과 시간이 임계값보다 큰가"로 이루어집니다. 경과 시간이 임계값과 같으면 callback은 호출되지 않습니다. 임계값을 `0`으로 하면 측정된 모든 transaction이 callback 대상이 됩니다.

## SQL 지연과 구분하기

Laravel에는 하나의 request 안에서 실행된 SQL의 누적 시간을 모니터링하는 `whenQueryingForLongerThan`도 있습니다. 두 API는 측정 대상이 다릅니다.

| API | 측정 대상 | callback의 event |
| - | - | - |
| `whenQueryingForLongerThan` | request 안의 SQL 실행 시간 누적 | `QueryExecuted` |
| `whenTransactionRunsLongerThan` | 바깥쪽 transaction 시작부터 commit 또는 rollback까지의 경과 시간 | `TransactionCommitted` 또는 `TransactionRolledBack` |

트랜잭션 안에서 외부 API를 호출하거나 락 대기가 발생하면 SQL 누적 시간보다 트랜잭션 경과 시간이 더 커질 수 있습니다. 두 가지를 모두 기록하면 지연이 SQL 자체 때문인지 트랜잭션 안의 다른 처리 때문인지 구분하기 쉬워집니다.

## 운영 시 주의할 점

callback은 commit 또는 rollback 처리 중에 호출되므로 모니터링용 처리로 한정합니다. 로그 출력이나 metrics 기록은 할 수 있지만, 같은 연결에서 추가 갱신을 실행하거나 시간이 걸리는 외부 통신을 하지 마세요.

또한 트랜잭션 안에서 외부 API를 호출하면 그 대기 시간도 측정됩니다. 외부 통신을 트랜잭션 밖으로 옮길 수 있는지 검토하면 알림을 줄일 뿐 아니라 락 보유 시간도 단축할 수 있습니다.

## 참고한 1차 자료

* [Laravel 공식 데이터베이스 문서](https://github.com/laravel/docs/blob/13.x/database.md)
* [`Connection::whenTransactionRunsLongerThan` 구현](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Connection.php)
* [Laravel Framework에 추가된 커밋](https://github.com/laravel/framework/commit/5edfeeed86961983042d0bdbbe7265d5b6dc7bba)


## Related topics

- [고급 주제](https://kawax.biz/ko/advanced/index.md)
- [Eloquent Observers와 모델 이벤트](https://kawax.biz/ko/advanced/eloquent-observers.md)
- [이벤트와 리스너](https://kawax.biz/ko/events.md)
- [Pest PHP로 시작하는 Laravel 테스트](https://kawax.biz/ko/blog/pest-introduction.md)
- [데이터베이스 테스트](https://kawax.biz/ko/database-testing.md)


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