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

# 패키지의 커스텀 Pulse 레코더

> Laravel Pulse의 레코더를 사용해 패키지 고유의 이벤트를 대시보드에 집계하는 방법을 해설합니다. listen을 통한 이벤트 구독, Pulse::record를 통한 집계, ignore와 sample_rate 설정, 예외 처리를 설명합니다.

Laravel Pulse는 요청, 쿼리, 잡 등을 대시보드에 집계합니다. 패키지가 독자적인 처리를 수행하는 경우, 커스텀 레코더를 사용하면 그 처리의 건수와 소요 시간을 Pulse에서 모니터링할 수 있습니다.

이 가이드에서는 패키지가 디스패치하는 이벤트를 구독하고 그 건수와 소요 시간을 기록하는 레코더를 만듭니다. Pulse의 기본적인 사용법은 [Pulse](https://kawax.biz/ko/pulse.md)를 참고하세요.

> [!NOTE]
>
> 이 가이드는 Pulse 1.11.0의 소스 코드를 바탕으로 합니다. 예제의 `ReportGenerated` 이벤트는 설명을 위한 가상의 클래스입니다. 실제 패키지에서는 자신의 이벤트로 바꿔 사용하세요.

## 처리 흐름

레코더는 이벤트를 받으면 Pulse의 버퍼에 기록을 쌓습니다. 버퍼는 수집(ingest) 시점에 한꺼번에 저장됩니다.

```mermaid theme={null}
flowchart LR
    A["이벤트 발생"] --> B["listen이<br>record를 호출"]
    B --> C["Pulse::record가<br>Entry를 생성"]
    C --> D["Pulse 버퍼"]
    D --> E["ingest로 저장"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["대시보드에 표시"]
    G --> H
```

## 레코더 만들기

레코더는 `listen` 프로퍼티에 구독할 이벤트를 선언하고, `record()` 메서드에 처리를 구현합니다. 아래 예제는 패키지가 디스패치하는 `ReportGenerated` 이벤트를 기록합니다. 이벤트는 `$type`과 `$durationMs` 프로퍼티를 가진다고 가정합니다.

```php theme={null}
<?php

namespace Acme\Reports\Pulse;

use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class ReportGenerationRecorder
{
    use Ignores, Sampling;

    public array $listen = [
        ReportGenerated::class,
    ];

    public function record(ReportGenerated $event): void
    {
        if ($this->shouldIgnore($event->type) || ! $this->shouldSample()) {
            return;
        }

        Pulse::record(
            type: 'report_generation',
            key: $event->type,
            value: $event->durationMs,
        )->count()->avg()->max();
    }
}
```

`Ignores`와 `Sampling` 트레이트는 아래에서 설명하는 `ignore`와 `sample_rate` 설정을 읽습니다.

## 애플리케이션에 레코더 등록하기

애플리케이션의 `config/pulse.php`에 있는 `recorders` 배열에 레코더를 등록합니다. 레코더의 클래스 이름을 키로 사용하고, 값으로 활성화 플래그와 설정을 지정합니다.

```php theme={null}
'recorders' => [
    // 기존 레코더는 그대로 둡니다
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider`는 `pulse.enabled`가 켜져 있을 때 `pulse.recorders`를 읽어 레코더를 등록합니다. `enabled`가 `false`인 레코더는 등록되지 않습니다. 이 설정을 패키지에서 자동으로 다시 쓰기보다는 설치 안내에 설정 예시를 보여 주는 편이 안전합니다.

## 집계의 종류

`Pulse::record()`는 `Entry`를 반환합니다. `count()`, `min()`, `max()`, `sum()`, `avg()`를 체이닝하면 해당 집계가 `pulse_aggregates`에 저장됩니다.

| 메서드 | 저장되는 값 |
| - | - |
| `count()` | 건수 |
| `min()` | 최솟값 |
| `max()` | 최댓값 |
| `sum()` | 합계 |
| `avg()` | 평균 |
| `onlyBuckets()` | `pulse_entries`에 개별 기록을 남기지 않고 집계 결과만 저장 |

`min()`, `max()`, `sum()`, `avg()`는 계산에 `value`를 사용합니다. `count()`만 사용할 때는 `value`가 필요 없습니다.

이벤트가 매우 자주 발생하는 경우 `onlyBuckets()`로 `pulse_entries`의 행 수를 줄일 수 있습니다.

## 문자열 값 저장하기

숫자를 집계하는 대신 최신 상태와 같은 문자열을 저장하고 싶을 때는 `Pulse::set()`을 사용합니다. 값은 `pulse_values` 테이블에 저장됩니다.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::set('report_status', $event->type, $event->status);
```

`value`는 `string`으로 전달해야 합니다.

## 무거운 처리 지연시키기

`Pulse::lazy()`에 전달한 클로저는 즉시 실행되지 않습니다. Pulse가 데이터를 수집할 때 실행됩니다. 기록에 시간이 걸려 응답을 보낸 뒤에 실행하고 싶을 때 사용합니다.

```php theme={null}
Pulse::lazy(function () use ($event) {
    Pulse::record('report_size', $event->type, $event->rows)->sum();
});
```

## 인증된 사용자 기록하기

인증된 사용자의 식별자가 필요할 때는 `Pulse::resolveAuthenticatedUserId()`를 사용합니다. 인증된 사용자가 없으면 `null`을 반환합니다.

```php theme={null}
$userId = Pulse::resolveAuthenticatedUserId();
```

## 제외, 샘플링, 필터

기록되는 양을 줄이려면 다음 네 가지를 사용합니다.

* `ignore` 설정: `shouldIgnore()`에 전달한 값이 정규 표현식 중 하나와 일치하면 기록을 건너뜁니다. 위 예제에서는 `$event->type`이 `/^debug_/`와 일치하는 이벤트를 건너뜁니다.
* `sample_rate` 설정: `shouldSample()`이 확인합니다. `1`은 모든 이벤트를 기록하고, `0.1`은 약 10%를 기록합니다.
* `Pulse::ignore()`: 콜백 안에서의 기록을 비활성화하고 콜백의 결과를 반환합니다.
* `Pulse::filter()`: 저장 전에 각 `Entry` 또는 `Value`를 받아 `true`를 반환한 항목만 저장합니다.

## 예외 처리

Pulse는 레코더의 처리와 수집을 `rescue()`로 감쌉니다. 레코더 안에서 던져진 예외는 애플리케이션까지 전달되지 않습니다. `handleExceptionsUsing()`이 설정되어 있지 않으면 예외는 조용히 버려집니다. 예외를 보고하려면 애플리케이션에서 설정합니다.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::handleExceptionsUsing(fn (Throwable $e) => report($e));
```

## 테스트

레코더를 테스트하려면 이벤트를 디스패치하고 `Pulse::ingest()`를 호출한 뒤 저장된 행을 확인할 수 있습니다. 아래 예제는 Pulse의 소스 코드에서 도출한 것이며 실행해 보지는 않았습니다. 테스트 환경에서 `pulse.enabled`가 켜져 있는지 확인하세요.

```php theme={null}
use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;

it('records ReportGenerated in pulse_entries', function () {
    event(new ReportGenerated(type: 'monthly', durationMs: 120));

    Pulse::ingest();

    $this->assertDatabaseHas('pulse_entries', [
        'type' => 'report_generation',
        'key' => 'monthly',
        'value' => 120,
    ]);
});
```

## 키 설계

`key`는 집계의 단위입니다. 사용자 ID나 URL처럼 끝없이 늘어나는 값을 사용하면 데이터 양이 늘어나고 집계를 읽기 어려워집니다. `key`에는 이벤트 종류나 프로세스 이름처럼 종류가 한정된 값을 사용하세요.


## Related topics

- [고급 주제](https://kawax.biz/ko/advanced/index.md)
- [패키지의 커스텀 UserProvider](https://kawax.biz/ko/advanced/package-user-providers.md)
- [패키지의 커스텀 세션 드라이버](https://kawax.biz/ko/advanced/package-session-drivers.md)
- [패키지의 커스텀 알림 채널과 전송 검증](https://kawax.biz/ko/advanced/package-notification-channels.md)
- [패키지의 커스텀 캐시 스토어와 계약](https://kawax.biz/ko/advanced/package-cache-drivers.md)


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