Laravel Pulse

소개
설치
- 구성
대시보드
엔트리 캡처
- 레코더
- 필터링
성능
사용자 정의 카드

소개

Laravel Pulse는 애플리케이션의 성능 및 사용량에 대한 한눈에 파악할 수 있는 통찰력을 제공합니다. Pulse를 사용하면 느린 작업 및 엔드포인트와 같은 병목 현상을 추적하고 가장 활성적인 사용자를 찾을 수 있습니다.

개별 이벤트의 심층적인 디버깅은 Laravel Telescope를 확인하십시오.

설치

Pulse의 기본 스토리지 구현은 현재 MySQL, MariaDB 또는 PostgreSQL 데이터베이스를 필요로 합니다. 다른 데이터베이스 엔진을 사용하는 경우 Pulse 데이터에 대한 별도의 MySQL, MariaDB 또는 PostgreSQL 데이터베이스가 필요합니다.

Composer 패키지 관리자를 사용하여 Pulse를 설치할 수 있습니다:

composer require laravel/pulse

다음으로 vendor:publish Artisan 명령을 사용하여 Pulse 구성 및 마이그레이션 파일을 게시해야 합니다:

php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

마지막으로 Pulse 데이터를 저장하는 데 필요한 테이블을 생성하기 위해 migrate 명령을 실행해야 합니다:

php artisan migrate

펄스의 데이터베이스 마이그레이션이 실행되면 /pulse 경로를 통해 펄스 대시보드에 접근할 수 있습니다.

애플리케이션의 기본 데이터베이스에 펄스 데이터를 저장하고 싶지 않다면, 전용 데이터베이스 연결을 지정할 수 있습니다.

구성

펄스의 많은 구성 옵션은 환경 변수를 사용하여 제어할 수 있습니다. 사용 가능한 옵션을 확인하거나, 새로운 레코더를 등록하거나, 고급 옵션을 구성하려면 config/pulse.php 구성 파일을 게시하면 됩니다.

php artisan vendor:publish --tag=pulse-config

펄스 대시보드는 /pulse 경로를 통해 접근할 수 있습니다. 기본적으로 local 환경에서만 이 대시보드에 접근할 수 있으므로, 'viewPulse' 권한 부여 게이트를 사용자 정의하여 프로덕션 환경에 대한 권한 부여를 구성해야 합니다. 애플리케이션의 app/Providers/AppServiceProvider.php 파일 내에서 이를 수행할 수 있습니다.

use App\Models\User;
use Illuminate\Support\Facades\Gate;
 
/**
 * 모든 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });
 
    // ...
}

사용자 정의

대시보드 뷰를 게시하여 펄스 대시보드 카드와 레이아웃을 구성할 수 있습니다. 대시보드 뷰는 resources/views/vendor/pulse/dashboard.blade.php에 게시됩니다.

php artisan vendor:publish --tag=pulse-dashboard

대시보드는 Livewire를 기반으로 하며, JavaScript 에셋을 다시 빌드할 필요 없이 카드와 레이아웃을 사용자 정의할 수 있습니다.

이 파일 내에서 <x-pulse> 컴포넌트는 대시보드를 렌더링하고 카드에 대한 그리드 레이아웃을 제공합니다. 대시보드가 화면 전체 너비를 차지하도록 하려면 컴포넌트에 full-width prop을 제공하면 됩니다.

<x-pulse full-width>
    ...
</x-pulse>

기본적으로 <x-pulse> 컴포넌트는 12개의 열 그리드를 생성하지만, cols prop을 사용하여 이를 사용자 정의할 수 있습니다.

<x-pulse cols="16">
    ...
</x-pulse>

각 카드는 cols 및 rows prop을 받아 공간과 위치를 제어합니다.

<livewire:pulse.usage cols="4" rows="2" />

대부분의 카드는 스크롤 대신 전체 카드를 표시하는 expand prop도 허용합니다.

<livewire:pulse.slow-queries expand />

사용자 확인

애플리케이션 사용량 카드와 같이 사용자에 대한 정보를 표시하는 카드의 경우, Pulse는 사용자의 ID만 기록합니다. 대시보드를 렌더링할 때 Pulse는 기본 Authenticatable 모델에서 name 및 email 필드를 확인하고 Gravatar 웹 서비스를 사용하여 아바타를 표시합니다.

애플리케이션의 App\Providers\AppServiceProvider 클래스 내에서 Pulse::user 메서드를 호출하여 필드와 아바타를 사용자 정의할 수 있습니다.

user 메서드는 표시할 Authenticatable 모델을 받는 클로저를 허용하며, 사용자에 대한 name, extra, avatar 정보를 포함하는 배열을 반환해야 합니다.

use Laravel\Pulse\Facades\Pulse;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);
 
    // ...
}

Laravel\Pulse\Contracts\ResolvesUsers 계약을 구현하고 Laravel의 서비스 컨테이너에 바인딩하여 인증된 사용자를 캡처하고 검색하는 방법을 완전히 사용자 정의할 수 있습니다.

카드

서버

<livewire:pulse.servers /> 카드는 pulse:check 명령을 실행하는 모든 서버의 시스템 리소스 사용량을 표시합니다. 시스템 리소스 보고에 대한 자세한 내용은 서버 레코더 관련 문서를 참조하십시오.

인프라에서 서버를 교체하는 경우, 주어진 기간 후에는 Pulse 대시보드에 비활성 서버를 표시하지 않도록 할 수 있습니다. ignore-after prop을 사용하여 이를 수행할 수 있으며, 이 prop은 비활성 서버가 Pulse 대시보드에서 제거되어야 하는 시간(초)을 받습니다. 또는 1 hour 또는 3 days and 1 hour과 같은 상대 시간 형식 문자열을 제공할 수도 있습니다.

<livewire:pulse.servers ignore-after="3 hours" />

애플리케이션 사용량

<livewire:pulse.usage /> 카드는 애플리케이션에 요청을 보내고, 작업을 디스패치하고, 느린 요청을 경험하는 상위 10명의 사용자를 표시합니다.

화면에 모든 사용량 메트릭을 동시에 보고 싶다면 카드를 여러 번 포함하고 type 속성을 지정할 수 있습니다.

<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />

Pulse가 사용자 정보를 가져오고 표시하는 방식을 사용자 정의하는 방법을 알아보려면 사용자 확인에 대한 문서를 참조하세요.

애플리케이션이 많은 요청을 받거나 많은 작업을 디스패치하는 경우 샘플링을 활성화하는 것이 좋습니다. 자세한 내용은 사용자 요청 기록기, 사용자 작업 기록기 및 느린 작업 기록기 문서를 참조하세요.

예외

<livewire:pulse.exceptions /> 카드는 애플리케이션에서 발생하는 예외의 빈도와 최근 발생 시간을 보여줍니다. 기본적으로 예외는 예외 클래스와 발생 위치를 기준으로 그룹화됩니다. 자세한 내용은 예외 기록기 문서를 참조하세요.

대기열

<livewire:pulse.queues /> 카드는 대기열에 있는 작업 수, 처리 중인 작업, 처리된 작업, 해제된 작업 및 실패한 작업을 포함하여 애플리케이션의 대기열 처리량을 보여줍니다. 자세한 내용은 대기열 기록기 문서를 참조하세요.

느린 요청

<livewire:pulse.slow-requests /> 카드는 구성된 임계값(기본값은 1,000ms)을 초과하는 애플리케이션에 대한 수신 요청을 보여줍니다. 자세한 내용은 느린 요청 기록기 문서를 참조하세요.

느린 작업

<livewire:pulse.slow-jobs /> 카드는 구성된 임계값(기본값은 1,000ms)을 초과하는 애플리케이션의 대기열에 있는 작업을 보여줍니다. 자세한 내용은 느린 작업 기록기 문서를 참조하세요.

느린 쿼리

<livewire:pulse.slow-queries /> 카드는 구성된 임계값(기본값은 1,000ms)을 초과하는 애플리케이션의 데이터베이스 쿼리를 보여줍니다.

기본적으로 느린 쿼리는 SQL 쿼리(바인딩 제외)와 발생 위치를 기준으로 그룹화되지만, SQL 쿼리만으로 그룹화하려면 위치를 캡처하지 않도록 선택할 수 있습니다.

매우 큰 SQL 쿼리가 구문 강조 표시되어 렌더링 성능 문제가 발생하는 경우 without-highlighting prop을 추가하여 강조 표시를 비활성화할 수 있습니다.

<livewire:pulse.slow-queries without-highlighting />

자세한 내용은 느린 쿼리 기록기 문서를 참조하세요.

느린 발신 요청

<livewire:pulse.slow-outgoing-requests /> 카드는 Laravel의 HTTP 클라이언트를 사용하여 이루어진 발신 요청 중 구성된 임계값(기본값은 1,000ms)을 초과하는 요청을 보여줍니다.

기본적으로 항목은 전체 URL별로 그룹화됩니다. 그러나 정규식을 사용하여 유사한 발신 요청을 정규화하거나 그룹화할 수 있습니다. 자세한 내용은 느린 발신 요청 기록기 문서를 참조하세요.

캐시

<livewire:pulse.cache /> 카드는 애플리케이션의 캐시 적중 및 실패 통계를 전체적으로나 개별 키별로 보여줍니다.

기본적으로 항목은 키별로 그룹화됩니다. 그러나 정규식을 사용하여 유사한 키를 정규화하거나 그룹화할 수 있습니다. 자세한 내용은 캐시 상호 작용 기록기 문서를 참조하세요.

항목 캡처

대부분의 Pulse 기록기는 Laravel에서 디스패치된 프레임워크 이벤트를 기반으로 항목을 자동으로 캡처합니다. 그러나 서버 기록기와 일부 타사 카드는 정보를 정기적으로 폴링해야 합니다. 이러한 카드를 사용하려면 모든 개별 애플리케이션 서버에서 pulse:check 데몬을 실행해야 합니다.

php artisan pulse:check

pulse:check 프로세스를 백그라운드에서 영구적으로 실행하려면 Supervisor와 같은 프로세스 모니터를 사용하여 명령이 실행을 멈추지 않도록 해야 합니다.

pulse:check 명령은 장기 실행 프로세스이므로 재시작하지 않으면 코드베이스의 변경 사항을 볼 수 없습니다. 애플리케이션 배포 프로세스 중에 pulse:restart 명령을 호출하여 명령을 정상적으로 재시작해야 합니다.

php artisan pulse:restart

Pulse는 재시작 신호를 저장하기 위해 캐시를 사용하므로, 이 기능을 사용하기 전에 애플리케이션에 캐시 드라이버가 올바르게 구성되었는지 확인해야 합니다.

레코더

레코더는 애플리케이션에서 Pulse 데이터베이스에 기록될 항목을 캡처하는 역할을 합니다. 레코더는 Pulse 구성 파일의 recorders 섹션에 등록 및 구성됩니다.

캐시 상호 작용

CacheInteractions 레코더는 캐시 카드에 표시하기 위해 애플리케이션에서 발생하는 캐시 히트 및 미스에 대한 정보를 캡처합니다.

선택적으로 샘플링 속도 및 무시된 키 패턴을 조정할 수 있습니다.

또한 유사한 키를 단일 항목으로 그룹화하도록 키 그룹화를 구성할 수도 있습니다. 예를 들어 동일한 유형의 정보를 캐싱하는 키에서 고유 ID를 제거할 수 있습니다. 그룹은 키의 일부를 "찾아서 바꾸는" 정규식을 사용하여 구성됩니다. 구성 파일에 예제가 포함되어 있습니다.

Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d+/' => ':*',
    ],
],

일치하는 첫 번째 패턴이 사용됩니다. 일치하는 패턴이 없으면 키는 있는 그대로 캡처됩니다.

예외

Exceptions 레코더는 예외 카드에 표시하기 위해 애플리케이션에서 발생하는 보고 가능한 예외에 대한 정보를 캡처합니다.

선택적으로 샘플링 속도 및 무시된 예외 패턴을 조정할 수 있습니다. 또한 예외가 발생한 위치를 캡처할지 여부를 구성할 수도 있습니다. 캡처된 위치는 예외의 원인을 추적하는 데 도움이 될 수 있는 Pulse 대시보드에 표시됩니다. 그러나 동일한 예외가 여러 위치에서 발생하면 고유한 각 위치에 대해 여러 번 표시됩니다.

큐

Queues 레코더는 큐에 표시하기 위해 애플리케이션 큐에 대한 정보를 캡처합니다.

선택적으로 샘플링 속도 및 무시된 작업 패턴을 조정할 수 있습니다.

느린 작업

SlowJobs 레코더는 느린 작업 카드에 표시하기 위해 애플리케이션에서 발생하는 느린 작업에 대한 정보를 캡처합니다.

선택적으로 느린 작업 임계값, 샘플링 속도 및 무시된 작업 패턴을 조정할 수 있습니다.

다른 작업보다 시간이 더 오래 걸릴 것으로 예상되는 작업이 있을 수 있습니다. 이러한 경우 작업별 임계값을 구성할 수 있습니다.

Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

작업의 클래스 이름과 일치하는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.

느린 발신 요청

SlowOutgoingRequests 레코더는 Laravel의 HTTP 클라이언트를 사용하여 이루어진 발신 HTTP 요청 중 구성된 임계값을 초과하는 요청에 대한 정보를 캡처하여 느린 발신 요청 카드에 표시합니다.

선택적으로 느린 발신 요청 임계값, 샘플링 속도 및 무시되는 URL 패턴을 조정할 수 있습니다.

다른 요청보다 시간이 더 오래 걸릴 것으로 예상되는 발신 요청이 있을 수 있습니다. 이러한 경우 요청별 임계값을 구성할 수 있습니다.

Recorders\SlowOutgoingRequests::class => [
    // ...
    'threshold' => [
        '#backup.zip$#' => 5000,
        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
    ],
],

요청 URL과 일치하는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.

또한 유사한 URL이 단일 항목으로 그룹화되도록 URL 그룹화를 구성할 수도 있습니다. 예를 들어 URL 경로에서 고유 ID를 제거하거나 도메인별로만 그룹화할 수 있습니다. 그룹은 URL의 일부를 "찾아서 바꾸기" 위해 정규 표현식을 사용하여 구성됩니다. 구성 파일에 몇 가지 예가 포함되어 있습니다.

Recorders\SlowOutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d+#' => '/*',
    ],
],

일치하는 첫 번째 패턴이 사용됩니다. 일치하는 패턴이 없으면 URL이 있는 그대로 캡처됩니다.

느린 쿼리

SlowQueries 레코더는 느린 쿼리 카드에 표시하기 위해 구성된 임계값을 초과하는 애플리케이션의 모든 데이터베이스 쿼리를 캡처합니다.

선택적으로 느린 쿼리 임계값, 샘플링 속도 및 무시된 쿼리 패턴을 조정할 수 있습니다. 쿼리 위치를 캡처할지 여부를 구성할 수도 있습니다. 캡처된 위치는 쿼리 원인을 추적하는 데 도움이 될 수 있는 Pulse 대시보드에 표시됩니다. 그러나 동일한 쿼리가 여러 위치에서 수행되면 고유한 각 위치에 대해 여러 번 표시됩니다.

다른 쿼리보다 시간이 더 오래 걸릴 것으로 예상되는 쿼리가 있을 수 있습니다. 이러한 경우 쿼리별 임계값을 구성할 수 있습니다.

Recorders\SlowQueries::class => [
    // ...
    'threshold' => [
        '#^insert into `yearly_reports`#' => 5000,
        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
    ],
],

쿼리의 SQL과 일치하는 정규식 패턴이 없으면 'default' 값이 사용됩니다.

느린 요청

Requests 레코더는 느린 요청 및 애플리케이션 사용량 카드에 표시하기 위해 애플리케이션에 대한 요청 정보를 캡처합니다.

선택적으로 느린 경로 임계값, 샘플링 속도 및 무시된 경로를 조정할 수 있습니다.

다른 요청보다 시간이 더 오래 걸릴 것으로 예상되는 요청이 있을 수 있습니다. 이러한 경우 요청별 임계값을 구성할 수 있습니다.

Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

정규 표현식 패턴이 요청의 URL과 일치하지 않으면 'default' 값이 사용됩니다.

서버

Servers 레코더는 서버 카드에 표시하기 위해 애플리케이션을 구동하는 서버의 CPU, 메모리 및 스토리지 사용량을 캡처합니다. 이 레코더는 모니터링하려는 각 서버에서 pulse:check 명령어가 실행 중이어야 합니다.

각 보고 서버는 고유한 이름을 가져야 합니다. 기본적으로 Pulse는 PHP의 gethostname 함수에서 반환된 값을 사용합니다. 이를 사용자 지정하려면 PULSE_SERVER_NAME 환경 변수를 설정할 수 있습니다.

PULSE_SERVER_NAME=load-balancer

Pulse 구성 파일에서는 모니터링되는 디렉터리를 사용자 지정할 수도 있습니다.

사용자 작업

UserJobs 레코더는 애플리케이션 사용량 카드에 표시하기 위해 애플리케이션에서 작업을 디스패치하는 사용자에 대한 정보를 캡처합니다.

선택적으로 샘플링 속도 및 무시되는 작업 패턴을 조정할 수 있습니다.

사용자 요청

UserRequests 레코더는 애플리케이션 사용량 카드에 표시하기 위해 애플리케이션에 요청을 보내는 사용자에 대한 정보를 캡처합니다.

선택적으로 샘플링 속도 및 무시되는 URL 패턴을 조정할 수 있습니다.

필터링

살펴본 것처럼 많은 레코더는 구성에서 요청 URL과 같은 값에 따라 들어오는 항목을 "무시"하는 기능을 제공합니다. 그러나 때로는 현재 인증된 사용자와 같은 다른 요소를 기반으로 레코드를 필터링하는 것이 유용할 수 있습니다. 이러한 레코드를 필터링하려면 Pulse의 filter 메서드에 클로저를 전달하면 됩니다. 일반적으로 filter 메서드는 애플리케이션의 AppServiceProvider의 boot 메서드 내에서 호출해야 합니다.

use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;
 
/**
 * 애플리케이션 서비스 부트스트랩.
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });
 
    // ...
}

성능

Pulse는 추가적인 인프라 없이 기존 애플리케이션에 바로 적용될 수 있도록 설계되었습니다. 그러나 트래픽이 많은 애플리케이션의 경우 Pulse가 애플리케이션 성능에 미치는 영향을 제거하는 몇 가지 방법이 있습니다.

다른 데이터베이스 사용

트래픽이 많은 애플리케이션의 경우, 애플리케이션 데이터베이스에 영향을 주지 않도록 Pulse 전용 데이터베이스 연결을 사용하는 것이 좋습니다.

PULSE_DB_CONNECTION 환경 변수를 설정하여 Pulse에서 사용하는 데이터베이스 연결을 사용자 정의할 수 있습니다.

PULSE_DB_CONNECTION=pulse

Redis 수집

Redis 수집에는 Redis 6.2 이상과 애플리케이션의 구성된 Redis 클라이언트 드라이버로 phpredis 또는 predis가 필요합니다.

기본적으로 Pulse는 HTTP 응답이 클라이언트로 전송되거나 작업이 처리된 후 구성된 데이터베이스 연결에 직접 항목을 저장합니다. 그러나 Pulse의 Redis 수집 드라이버를 사용하여 항목을 Redis 스트림으로 보낼 수 있습니다. 이는 PULSE_INGEST_DRIVER 환경 변수를 구성하여 활성화할 수 있습니다.

PULSE_INGEST_DRIVER=redis

Pulse는 기본적으로 기본 Redis 연결을 사용하지만, PULSE_REDIS_CONNECTION 환경 변수를 통해 사용자 정의할 수 있습니다.

PULSE_REDIS_CONNECTION=pulse

Redis 수집을 사용하는 경우 pulse:work 명령을 실행하여 스트림을 모니터링하고 Redis의 항목을 Pulse의 데이터베이스 테이블로 이동해야 합니다.

php artisan pulse:work

pulse:work 프로세스를 백그라운드에서 영구적으로 실행하려면 Supervisor와 같은 프로세스 모니터를 사용하여 Pulse 작업자가 실행을 멈추지 않도록 해야 합니다.

pulse:work 명령어는 장기 실행 프로세스이므로 재시작하지 않으면 코드베이스의 변경 사항을 반영하지 않습니다. 애플리케이션 배포 프로세스 중에 pulse:restart 명령어를 호출하여 명령어를 정상적으로 재시작해야 합니다.

php artisan pulse:restart

Pulse는 재시작 신호를 저장하기 위해 캐시를 사용하므로 이 기능을 사용하기 전에 애플리케이션에 캐시 드라이버가 올바르게 구성되어 있는지 확인해야 합니다.

샘플링

기본적으로 Pulse는 애플리케이션에서 발생하는 모든 관련 이벤트를 캡처합니다. 트래픽이 많은 애플리케이션의 경우, 특히 장기간에 걸쳐 대시보드에서 수백만 개의 데이터베이스 행을 집계해야 할 수 있습니다.

대신 특정 Pulse 데이터 레코더에서 "샘플링"을 활성화하도록 선택할 수 있습니다. 예를 들어, 사용자 요청 레코더에서 샘플링 속도를 0.1로 설정하면 애플리케이션에 대한 요청의 약 10%만 기록됩니다. 대시보드에서 값은 근사값임을 나타내기 위해 ~ 접두사가 붙고 스케일 업됩니다.

일반적으로 특정 메트릭에 대한 항목이 많을수록 정확도를 크게 희생하지 않고 샘플링 속도를 더 낮게 설정할 수 있습니다.

트리밍

Pulse는 대시보드 창 외부에 있는 저장된 항목을 자동으로 트리밍합니다. 트리밍은 Pulse 구성 파일에서 사용자 정의할 수 있는 로터리 시스템을 사용하여 데이터를 수집할 때 발생합니다.

Pulse 예외 처리

스토리지 데이터베이스에 연결할 수 없는 등 Pulse 데이터를 캡처하는 동안 예외가 발생하면 애플리케이션에 영향을 미치지 않도록 Pulse는 자동으로 실패합니다.

이러한 예외가 처리되는 방식을 사용자 정의하려면 handleExceptionsUsing 메서드에 클로저를 제공할 수 있습니다.

use Laravel\Pulse\Facades\Pulse;
use Illuminate\Support\Facades\Log;
 
Pulse::handleExceptionsUsing(function ($e) {
    Log::debug('An exception happened in Pulse', [
        'message' => $e->getMessage(),
        'stack' => $e->getTraceAsString(),
    ]);
});

사용자 정의 카드

Pulse를 사용하면 애플리케이션의 특정 요구 사항과 관련된 데이터를 표시하는 사용자 정의 카드를 만들 수 있습니다. Pulse는 Livewire를 사용하므로 첫 번째 사용자 정의 카드를 만들기 전에 해당 문서를 검토하는 것이 좋습니다.

카드 컴포넌트

Laravel Pulse에서 사용자 정의 카드를 만드는 것은 기본 Card Livewire 컴포넌트를 확장하고 해당 뷰를 정의하는 것으로 시작합니다.

namespace App\Livewire\Pulse;
 
use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;
 
#[Lazy]
class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers');
    }
}

Livewire의 지연 로딩 기능을 사용할 때 Card 컴포넌트는 컴포넌트에 전달된 cols 및 rows 속성을 존중하는 자리 표시자를 자동으로 제공합니다.

Pulse 카드에 해당하는 뷰를 작성할 때 일관된 모양과 느낌을 위해 Pulse의 Blade 컴포넌트를 활용할 수 있습니다.

<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
    <x-pulse::card-header name="Top Sellers">
        <x-slot:icon>
            ...
        </x-slot:icon>
    </x-pulse::card-header>
 
    <x-pulse::scroll :expand="$expand">
        ...
    </x-pulse::scroll>
</x-pulse::card>

$cols, $rows, $class 및 $expand 변수는 해당 Blade 컴포넌트에 전달되어 카드 레이아웃을 대시보드 뷰에서 사용자 정의할 수 있도록 해야 합니다. 또한 카드가 자동으로 업데이트되도록 뷰에 wire:poll.5s="" 속성을 포함할 수도 있습니다.

Livewire 컴포넌트와 템플릿을 정의했으면 대시보드 뷰에 카드를 포함할 수 있습니다.

<x-pulse>
    ...
 
    <livewire:pulse.top-sellers cols="4" />
</x-pulse>

카드가 패키지에 포함된 경우, Livewire::component 메서드를 사용하여 Livewire에 컴포넌트를 등록해야 합니다.

스타일링

카드가 Pulse에 포함된 클래스 및 컴포넌트 외에 추가적인 스타일링이 필요한 경우, 카드에 사용자 지정 CSS를 포함하는 몇 가지 옵션이 있습니다.

Laravel Vite 통합

사용자 지정 카드가 애플리케이션 코드 베이스 내에 있고 Laravel의 Vite 통합을 사용하는 경우, vite.config.js 파일을 업데이트하여 카드에 대한 전용 CSS 진입점을 포함할 수 있습니다:

laravel({
    input: [
        'resources/css/pulse/top-sellers.css',
        // ...
    ],
}),

그런 다음 대시보드 뷰에서 @vite Blade 지시어를 사용하여 카드에 대한 CSS 진입점을 지정할 수 있습니다:

<x-pulse>
    @vite('resources/css/pulse/top-sellers.css')
 
    ...
</x-pulse>

CSS 파일

패키지에 포함된 Pulse 카드를 포함한 다른 사용 사례의 경우, Livewire 컴포넌트에 CSS 파일의 파일 경로를 반환하는 css 메서드를 정의하여 Pulse가 추가 스타일시트를 로드하도록 지시할 수 있습니다:

class TopSellers extends Card
{
    // ...
 
    protected function css()
    {
        return __DIR__.'/../../dist/top-sellers.css';
    }
}

이 카드가 대시보드에 포함되면 Pulse는 자동으로 이 파일의 내용을 <style> 태그 내에 포함하므로 public 디렉토리에 게시할 필요가 없습니다.

Tailwind CSS

Tailwind CSS를 사용하는 경우, 불필요한 CSS 로딩이나 Pulse의 Tailwind 클래스와의 충돌을 피하기 위해 전용 Tailwind 구성 파일을 생성해야 합니다.

export default {
    darkMode: 'class',
    important: '#top-sellers',
    content: [
        './resources/views/livewire/pulse/top-sellers.blade.php',
    ],
    corePlugins: {
        preflight: false,
    },
};

그런 다음 CSS 진입점에 구성 파일을 지정할 수 있습니다:

@config "../../tailwind.top-sellers.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;

또한 Tailwind의 important 선택기 전략에 전달된 선택자와 일치하는 id 또는 class 속성을 카드 보기에 포함해야 합니다.

<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
    ...
</x-pulse::card>

데이터 캡처 및 집계

사용자 정의 카드는 어디에서든 데이터를 가져와서 표시할 수 있습니다. 하지만 Pulse의 강력하고 효율적인 데이터 기록 및 집계 시스템을 활용하고 싶을 수도 있습니다.

항목 캡처

Pulse를 사용하면 Pulse::record 메서드를 사용하여 "항목"을 기록할 수 있습니다:

use Laravel\Pulse\Facades\Pulse;
 
Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();

record 메서드에 제공되는 첫 번째 인수는 기록하는 항목의 type이고, 두 번째 인수는 집계된 데이터를 그룹화하는 방법을 결정하는 key입니다. 대부분의 집계 메서드의 경우 집계할 value를 지정해야 합니다. 위의 예에서 집계되는 값은 $sale->amount입니다. 그런 다음 Pulse가 나중에 효율적으로 검색할 수 있도록 미리 집계된 값을 "버킷"에 캡처할 수 있도록 하나 이상의 집계 메서드(sum과 같은)를 호출할 수 있습니다.

사용 가능한 집계 메서드는 다음과 같습니다.

avg
count
max
min
sum

현재 인증된 사용자 ID를 캡처하는 카드 패키지를 빌드할 때 애플리케이션에 적용된 모든 사용자 리졸버 사용자 지정을 준수하는 Pulse::resolveAuthenticatedUserId() 메서드를 사용해야 합니다.

집계 데이터 검색

Pulse의 Card Livewire 컴포넌트를 확장할 때 aggregate 메서드를 사용하여 대시보드에서 보고 있는 기간에 대한 집계 데이터를 검색할 수 있습니다.

class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers', [
            'topSellers' => $this->aggregate('user_sale', ['sum', 'count'])
        ]);
    }
}

aggregate 메서드는 PHP stdClass 객체 컬렉션을 반환합니다. 각 객체에는 이전에 캡처된 key 속성과 요청된 각 집계에 대한 키가 포함됩니다.

@foreach ($topSellers as $seller)
    {{ $seller->key }}
    {{ $seller->sum }}
    {{ $seller->count }}
@endforeach

Pulse는 주로 미리 집계된 버킷에서 데이터를 검색합니다. 따라서 지정된 집계는 Pulse::record 메서드를 사용하여 미리 캡처되어 있어야 합니다. 가장 오래된 버킷은 일반적으로 기간의 일부만 해당하므로, Pulse는 가장 오래된 항목을 집계하여 간격을 메우고 각 폴 요청 시 전체 기간을 집계할 필요 없이 전체 기간에 대한 정확한 값을 제공합니다.

aggregateTotal 메서드를 사용하여 특정 유형에 대한 총합을 검색할 수도 있습니다. 예를 들어, 다음 메서드는 사용자별로 그룹화하는 대신 모든 사용자 판매의 총합을 검색합니다.

$total = $this->aggregateTotal('user_sale', 'sum');

사용자 표시

사용자 ID를 키로 기록하는 집계를 사용하는 경우, Pulse::resolveUsers 메서드를 사용하여 키를 사용자 레코드로 확인할 수 있습니다.

$aggregates = $this->aggregate('user_sale', ['sum', 'count']);
 
$users = Pulse::resolveUsers($aggregates->pluck('key'));
 
return view('livewire.pulse.top-sellers', [
    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
        'user' => $users->find($aggregate->key),
        'sum' => $aggregate->sum,
        'count' => $aggregate->count,
    ])
]);

find 메서드는 name, extra, avatar 키를 포함하는 객체를 반환하며, 이 키는 선택적으로 <x-pulse::user-card> Blade 컴포넌트로 직접 전달할 수 있습니다.

<x-pulse::user-card :user="{{ $seller->user }}" :stats="{{ $seller->sum }}" />

사용자 정의 레코더

패키지 작성자는 사용자가 데이터 캡처를 구성할 수 있도록 레코더 클래스를 제공할 수 있습니다.

레코더는 애플리케이션의 config/pulse.php 구성 파일의 recorders 섹션에 등록됩니다.

[
    // ...
    'recorders' => [
        Acme\Recorders\Deployments::class => [
            // ...
        ],
 
        // ...
    ],
]

레코더는 $listen 속성을 지정하여 이벤트를 수신할 수 있습니다. Pulse는 자동으로 리스너를 등록하고 레코더의 record 메서드를 호출합니다.

<?php
 
namespace Acme\Recorders;
 
use Acme\Events\Deployment;
use Illuminate\Support\Facades\Config;
use Laravel\Pulse\Facades\Pulse;
 
class Deployments
{
    /**
     * The events to listen for.
     *
     * @var array<int, class-string>
     */
    public array $listen = [
        Deployment::class,
    ];
 
    /**
     * Record the deployment.
     */
    public function record(Deployment $event): void
    {
        $config = Config::get('pulse.recorders.'.static::class);
 
        Pulse::record(
            // ...
        );
    }
}