Laravel Pulse
업데이트됨번역일: 2026년 11월 9일
이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.
- 원문 수정
- 2026년 11월 6일
- 번역 갱신
- 2026년 11월 9일
Laravel Pulse
소개
Laravel Pulse는 애플리케이션의 성능과 사용 현황을 한눈에 파악할 수 있게 해 줍니다. Pulse를 사용하면 느린 Job이나 엔드포인트 같은 병목 지점을 찾아내고, 가장 활발하게 활동하는 사용자를 확인하는 등의 작업을 할 수 있습니다.
개별 이벤트를 깊이 있게 디버깅해야 한다면 Laravel Telescope를 참고하세요.
설치
WARNING
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"마지막으로 migrate 명령어를 실행해 Pulse 데이터를 저장하는 데 필요한 테이블을 생성합니다.
php artisan migratePulse의 데이터베이스 마이그레이션까지 실행했다면 /pulse 라우트를 통해 Pulse 대시보드에 접근할 수 있습니다.
NOTE
Pulse 데이터를 애플리케이션의 기본 데이터베이스에 저장하고 싶지 않다면 전용 데이터베이스 커넥션을 지정할 수 있습니다.
설정
Pulse의 많은 설정 옵션은 환경 변수로 제어할 수 있습니다. 사용 가능한 옵션을 확인하거나, 새 레코더를 등록하거나, 고급 옵션을 설정하려면 config/pulse.php 설정 파일을 퍼블리시하면 됩니다.
php artisan vendor:publish --tag=pulse-config캐시 설정에 serializable_classes 배열을 정의해 두었다면, 기본 Pulse 카드를 지원하기 위해 아래 클래스들을 해당 배열에 추가해야 합니다.
'serializable_classes' => [
// ...
Carbon\CarbonImmutable::class,
Illuminate\Support\Collection::class,
stdClass::class,
],대시보드
인가
Pulse 대시보드는 /pulse 라우트로 접근합니다. 기본적으로는 local 환경에서만 대시보드에 접근할 수 있으므로, 운영 환경에서 사용하려면 'viewPulse' 인가 게이트를 커스터마이징해 접근 권한을 설정해야 합니다. 애플리케이션의 app/Providers/AppServiceProvider.php 파일에서 다음과 같이 정의할 수 있습니다.
use App\Models\User;
use Illuminate\Support\Facades\Gate;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Gate::define('viewPulse', function (User $user) {
return $user->isAdmin();
});
// ...
}NOTE
위 예시는 isAdmin()이 true인 사용자만 대시보드를 볼 수 있게 합니다. 실제 프로젝트에서는 관리자 역할 판별 로직이나 특정 이메일(사내 계정 등)만 허용하는 조건 등으로 바꿔 사용하면 됩니다.
커스터마이징
대시보드 뷰를 퍼블리시하면 Pulse 대시보드의 카드와 레이아웃을 설정할 수 있습니다. 대시보드 뷰는 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 />사용자 확인
Application Usage 카드처럼 사용자 정보를 표시하는 카드의 경우, 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,
]);
// ...
}NOTE
Laravel\Pulse\Contracts\ResolvesUsers 계약(Contract)을 구현하고 Laravel 서비스 컨테이너에 바인딩하면, 인증된 사용자를 수집하고 조회하는 방식을 완전히 커스터마이징할 수 있습니다.
카드
Servers
<livewire:pulse.servers /> 카드는 pulse:check 명령어를 실행 중인 모든 서버의 시스템 리소스 사용량을 표시합니다. 시스템 리소스 보고에 대한 자세한 내용은 서버 레코더 문서를 참고하세요.
인프라의 서버를 교체했다면, 일정 시간이 지난 뒤에는 비활성 서버를 Pulse 대시보드에 더 이상 표시하지 않도록 하고 싶을 수 있습니다. 이때는 ignore-after prop을 사용합니다. 이 prop은 비활성 서버를 대시보드에서 제거할 기준 시간(초)을 받으며, 1 hour나 3 days and 1 hour처럼 상대 시간 형식의 문자열도 사용할 수 있습니다.
<livewire:pulse.servers ignore-after="3 hours" />Application Usage
<livewire:pulse.usage /> 카드는 애플리케이션에 요청을 보내거나, Job을 디스패치하거나, 느린 요청을 겪은 상위 10명의 사용자를 표시합니다.
모든 사용 지표를 한 화면에서 보고 싶다면 이 카드를 여러 번 포함하고 type 속성을 지정하면 됩니다.
<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />Pulse가 사용자 정보를 조회하고 표시하는 방식을 커스터마이징하는 방법은 사용자 확인 문서를 참고하세요.
NOTE
애플리케이션에 요청이 많거나 Job을 많이 디스패치한다면 샘플링을 활성화하는 것이 좋습니다. 자세한 내용은 사용자 요청 레코더, 사용자 Job 레코더, 느린 Job 레코더 문서를 참고하세요.
Exceptions
<livewire:pulse.exceptions /> 카드는 애플리케이션에서 발생하는 예외의 빈도와 최근 발생 시점을 보여 줍니다. 기본적으로 예외는 예외 클래스와 발생 위치를 기준으로 그룹화됩니다. 자세한 내용은 예외 레코더 문서를 참고하세요.
Queues
<livewire:pulse.queues /> 카드는 애플리케이션 큐의 처리량을 보여 줍니다. 대기 중인(queued), 처리 중인(processing), 처리 완료된(processed), 해제된(released), 실패한(failed) Job의 수가 포함됩니다. 자세한 내용은 큐 레코더 문서를 참고하세요.
Slow Requests
<livewire:pulse.slow-requests /> 카드는 설정된 임계값(기본값 1,000ms)을 초과한 애플리케이션의 수신 요청을 보여 줍니다. 자세한 내용은 느린 요청 레코더 문서를 참고하세요.
Slow Jobs
<livewire:pulse.slow-jobs /> 카드는 설정된 임계값(기본값 1,000ms)을 초과한 애플리케이션의 큐 Job을 보여 줍니다. 자세한 내용은 느린 Job 레코더 문서를 참고하세요.
Slow Queries
<livewire:pulse.slow-queries /> 카드는 설정된 임계값(기본값 1,000ms)을 초과한 애플리케이션의 데이터베이스 쿼리를 보여 줍니다.
기본적으로 느린 쿼리는 (바인딩을 제외한) SQL 쿼리와 쿼리가 발생한 위치를 기준으로 그룹화됩니다. 위치를 수집하지 않도록 설정하면 SQL 쿼리만을 기준으로 그룹화할 수도 있습니다.
매우 긴 SQL 쿼리에 구문 강조(syntax highlighting)를 적용하다가 렌더링 성능 문제가 생긴다면 without-highlighting prop을 추가해 강조 기능을 끌 수 있습니다.
<livewire:pulse.slow-queries without-highlighting />자세한 내용은 느린 쿼리 레코더 문서를 참고하세요.
Slow Outgoing Requests
<livewire:pulse.slow-outgoing-requests /> 카드는 Laravel의 HTTP 클라이언트로 보낸 외부 요청 중 설정된 임계값(기본값 1,000ms)을 초과한 요청을 보여 줍니다.
기본적으로 엔트리는 전체 URL을 기준으로 그룹화됩니다. 하지만 정규 표현식을 사용해 비슷한 외부 요청을 정규화하거나 하나로 묶고 싶을 수도 있습니다. 자세한 내용은 느린 외부 요청 레코더 문서를 참고하세요.
Cache
<livewire:pulse.cache /> 카드는 애플리케이션 전체 및 개별 키별 캐시 적중(hit)과 미스(miss) 통계를 보여 줍니다.
기본적으로 엔트리는 키를 기준으로 그룹화됩니다. 하지만 정규 표현식을 사용해 비슷한 키를 정규화하거나 하나로 묶고 싶을 수도 있습니다. 자세한 내용은 캐시 상호작용 레코더 문서를 참고하세요.
엔트리 수집
대부분의 Pulse 레코더는 Laravel이 디스패치하는 프레임워크 이벤트를 기반으로 엔트리를 자동 수집합니다. 다만 서버 레코더와 일부 서드파티 카드는 정보를 주기적으로 폴링해야 합니다. 이러한 카드를 사용하려면 모든 애플리케이션 서버에서 pulse:check 데몬을 실행해야 합니다.
php artisan pulse:checkNOTE
pulse:check 프로세스를 백그라운드에서 항상 실행 상태로 유지하려면 Supervisor 같은 프로세스 모니터를 사용해 명령어가 중단되지 않도록 해야 합니다.
pulse:check 명령어는 오래 실행되는(long-lived) 프로세스이므로, 재시작하지 않으면 코드베이스의 변경 사항이 반영되지 않습니다. 애플리케이션 배포 과정에서 pulse:restart 명령어를 호출해 안전하게(gracefully) 재시작하세요.
php artisan pulse:restartNOTE
Pulse는 재시작 신호를 저장하는 데 캐시를 사용하므로, 이 기능을 사용하기 전에 애플리케이션에 캐시 드라이버가 올바르게 설정되어 있는지 확인하세요.
레코더
레코더는 애플리케이션에서 엔트리를 수집해 Pulse 데이터베이스에 기록하는 역할을 합니다. 레코더는 Pulse 설정 파일의 recorders 섹션에서 등록하고 설정합니다.
Cache Interactions
CacheInteractions 레코더는 애플리케이션에서 발생하는 캐시 적중과 미스 정보를 수집해 Cache 카드에 표시합니다.
샘플링 비율과 무시할 키 패턴을 필요에 따라 조정할 수 있습니다.
또한 키 그룹화를 설정해 비슷한 키를 하나의 엔트리로 묶을 수도 있습니다. 예를 들어 같은 종류의 정보를 캐싱하는 키에서 고유 ID 부분을 제거하고 싶을 수 있습니다. 그룹은 키의 일부를 "찾아 바꾸는" 정규 표현식으로 설정하며, 설정 파일에 예시가 포함되어 있습니다.
Recorders\CacheInteractions::class => [
// ...
'groups' => [
// '/:\d+/' => ':*',
],
],일치하는 첫 번째 패턴이 사용됩니다. 일치하는 패턴이 없으면 키는 있는 그대로 수집됩니다.
Exceptions
Exceptions 레코더는 애플리케이션에서 발생하는 보고 가능한(reportable) 예외 정보를 수집해 Exceptions 카드에 표시합니다.
샘플링 비율과 무시할 예외 패턴을 필요에 따라 조정할 수 있으며, 예외가 발생한 위치를 수집할지 여부도 설정할 수 있습니다. 수집된 위치는 Pulse 대시보드에 표시되어 예외의 발생 지점을 추적하는 데 도움이 됩니다. 다만 같은 예외가 여러 위치에서 발생하면 위치별로 각각 별도의 엔트리로 표시됩니다.
Queues
Queues 레코더는 애플리케이션 큐에 관한 정보를 수집해 Queues 카드에 표시합니다.
샘플링 비율과 무시할 Job 패턴을 필요에 따라 조정할 수 있습니다.
Slow Jobs
SlowJobs 레코더는 애플리케이션에서 발생하는 느린 Job 정보를 수집해 Slow Jobs 카드에 표시합니다.
느린 Job의 임계값, 샘플링 비율, 무시할 Job 패턴을 필요에 따라 조정할 수 있습니다.
어떤 Job은 다른 Job보다 오래 걸리는 것이 당연할 수 있습니다. 이럴 때는 Job별 임계값을 설정할 수 있습니다.
Recorders\SlowJobs::class => [
// ...
'threshold' => [
'#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
],
],Job의 클래스명과 일치하는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.
Slow Outgoing Requests
SlowOutgoingRequests 레코더는 Laravel의 HTTP 클라이언트로 보낸 외부 HTTP 요청 중 설정된 임계값을 초과한 요청의 정보를 수집해 Slow Outgoing Requests 카드에 표시합니다.
느린 외부 요청의 임계값, 샘플링 비율, 무시할 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은 있는 그대로 수집됩니다.
Slow Queries
SlowQueries 레코더는 설정된 임계값을 초과한 애플리케이션의 모든 데이터베이스 쿼리를 수집해 Slow Queries 카드에 표시합니다.
느린 쿼리의 임계값, 샘플링 비율, 무시할 쿼리 패턴을 필요에 따라 조정할 수 있으며, 쿼리 위치를 수집할지 여부도 설정할 수 있습니다. 수집된 위치는 Pulse 대시보드에 표시되어 쿼리의 발생 지점을 추적하는 데 도움이 됩니다. 다만 같은 쿼리가 여러 위치에서 실행되면 위치별로 각각 별도의 엔트리로 표시됩니다.
어떤 쿼리는 다른 쿼리보다 오래 걸리는 것이 당연할 수 있습니다. 이럴 때는 쿼리별 임계값을 설정할 수 있습니다.
Recorders\SlowQueries::class => [
// ...
'threshold' => [
'#^insert into `yearly_reports`#' => 5000,
'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
],
],쿼리의 SQL과 일치하는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.
Slow Requests
Requests 레코더는 애플리케이션에 들어오는 요청 정보를 수집해 Slow Requests 카드와 Application Usage 카드에 표시합니다.
느린 라우트의 임계값, 샘플링 비율, 무시할 경로를 필요에 따라 조정할 수 있습니다.
어떤 요청은 다른 요청보다 오래 걸리는 것이 당연할 수 있습니다. 이럴 때는 요청별 임계값을 설정할 수 있습니다.
Recorders\SlowRequests::class => [
// ...
'threshold' => [
'#^/admin/#' => 5000,
'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
],
],요청 URL과 일치하는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.
Servers
Servers 레코더는 애플리케이션을 구동하는 서버의 CPU, 메모리, 스토리지 사용량을 수집해 Servers 카드에 표시합니다. 이 레코더를 사용하려면 모니터링하려는 각 서버에서 pulse:check 명령어가 실행 중이어야 합니다.
보고하는 각 서버는 고유한 이름을 가져야 합니다. 기본적으로 Pulse는 PHP의 gethostname 함수가 반환하는 값을 사용합니다. 이를 바꾸고 싶다면 PULSE_SERVER_NAME 환경 변수를 설정하세요.
PULSE_SERVER_NAME=load-balancerPulse 설정 파일에서는 모니터링할 디렉터리도 지정할 수 있습니다.
User Jobs
UserJobs 레코더는 애플리케이션에서 Job을 디스패치하는 사용자 정보를 수집해 Application Usage 카드에 표시합니다.
샘플링 비율과 무시할 Job 패턴을 필요에 따라 조정할 수 있습니다.
User Requests
UserRequests 레코더는 애플리케이션에 요청을 보내는 사용자 정보를 수집해 Application Usage 카드에 표시합니다.
샘플링 비율과 무시할 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;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Pulse::filter(function (Entry|Value $entry) {
return Auth::user()->isNotAdmin();
});
// ...
}성능
Pulse는 추가 인프라 없이 기존 애플리케이션에 바로 적용할 수 있도록 설계되었습니다. 다만 트래픽이 많은 애플리케이션에서는 Pulse가 애플리케이션 성능에 미칠 수 있는 영향을 줄이는 몇 가지 방법이 있습니다.
다른 데이터베이스 사용하기
트래픽이 많은 애플리케이션이라면 애플리케이션 데이터베이스에 영향을 주지 않도록 Pulse 전용 데이터베이스 커넥션을 사용하는 것이 좋습니다.
PULSE_DB_CONNECTION 환경 변수를 설정하면 Pulse가 사용하는 데이터베이스 커넥션을 바꿀 수 있습니다.
PULSE_DB_CONNECTION=pulseRedis 인제스트
WARNING
Redis 인제스트를 사용하려면 Redis 6.2 이상이 필요하며, 애플리케이션에 설정된 Redis 클라이언트 드라이버가 phpredis 또는 predis여야 합니다.
기본적으로 Pulse는 HTTP 응답이 클라이언트로 전송되었거나 Job 처리가 끝난 뒤에 설정된 데이터베이스 커넥션에 엔트리를 직접 저장합니다. 대신 Pulse의 Redis 인제스트 드라이버를 사용해 엔트리를 Redis 스트림으로 보낼 수도 있습니다. PULSE_INGEST_DRIVER 환경 변수를 설정하면 활성화됩니다.
PULSE_INGEST_DRIVER=redisPulse는 기본적으로 기본 Redis 커넥션을 사용하지만, PULSE_REDIS_CONNECTION 환경 변수로 변경할 수 있습니다.
PULSE_REDIS_CONNECTION=pulseWARNING
Redis 인제스트 드라이버를 사용할 때는, Redis 기반 큐를 함께 사용한다면 Pulse가 그 큐와는 항상 다른 Redis 커넥션을 사용하도록 해야 합니다.
Redis 인제스트를 사용하면 스트림을 감시하면서 Redis의 엔트리를 Pulse 데이터베이스 테이블로 옮기는 pulse:work 명령어를 실행해야 합니다.
php artisan pulse:workNOTE
pulse:work 프로세스를 백그라운드에서 항상 실행 상태로 유지하려면 Supervisor 같은 프로세스 모니터를 사용해 Pulse 워커가 중단되지 않도록 해야 합니다.
pulse:work 명령어는 오래 실행되는(long-lived) 프로세스이므로, 재시작하지 않으면 코드베이스의 변경 사항이 반영되지 않습니다. 애플리케이션 배포 과정에서 pulse:restart 명령어를 호출해 안전하게(gracefully) 재시작하세요.
php artisan pulse:restartNOTE
Pulse는 재시작 신호를 저장하는 데 캐시를 사용하므로, 이 기능을 사용하기 전에 애플리케이션에 캐시 드라이버가 올바르게 설정되어 있는지 확인하세요.
샘플링
기본적으로 Pulse는 애플리케이션에서 발생하는 모든 관련 이벤트를 수집합니다. 트래픽이 많은 애플리케이션에서는 특히 긴 기간을 조회할 때 대시보드에서 수백만 개의 데이터베이스 행을 집계해야 할 수 있습니다.
이럴 때는 일부 Pulse 데이터 레코더에 "샘플링"을 켜는 방법이 있습니다. 예를 들어 User Requests 레코더의 샘플링 비율을 0.1로 설정하면 애플리케이션 요청의 약 10%만 기록합니다. 대시보드에서는 값이 그에 맞게 환산되어 표시되며, 근사값임을 나타내기 위해 앞에 ~가 붙습니다.
일반적으로 특정 지표의 엔트리가 많을수록 정확도를 크게 해치지 않으면서 샘플링 비율을 더 낮게 설정할 수 있습니다.
트리밍
Pulse는 저장된 엔트리가 대시보드 조회 기간을 벗어나면 자동으로 정리(trim)합니다. 트리밍은 데이터를 인제스트할 때 로터리(lottery) 방식으로 실행되며, 이 동작은 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를 사용하므로, 첫 커스텀 카드를 만들기 전에 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의 지연 로딩(lazy loading) 기능을 사용하면, 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>NOTE
카드가 패키지에 포함되어 있다면 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의 Preflight 기본 스타일을 제외하고, Pulse의 Tailwind 클래스와 충돌하지 않도록 CSS 선택자로 Tailwind의 범위를 한정합니다.
@import "tailwindcss/theme.css";
@custom-variant dark (&:where(.dark, .dark *));
@source "./../../views/livewire/pulse/top-sellers.blade.php";
@theme {
/* ... */
}
#top-sellers {
@import "tailwindcss/utilities.css" source(none);
}또한 카드 뷰에는 엔트리 포인트의 CSS 선택자와 일치하는 id 또는 class 속성을 포함해야 합니다.
<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
...
</x-pulse::card>데이터 수집과 집계
커스텀 카드는 어디서든 데이터를 가져와 표시할 수 있습니다. 다만 Pulse의 강력하고 효율적인 데이터 기록 및 집계 시스템을 활용하고 싶을 수도 있습니다.
엔트리 수집
Pulse::record 메서드를 사용하면 "엔트리"를 기록할 수 있습니다.
use Laravel\Pulse\Facades\Pulse;
Pulse::record('user_sale', $user->id, $sale->amount)
->sum()
->count();record 메서드의 첫 번째 인자는 기록하려는 엔트리의 type이고, 두 번째 인자는 집계 데이터를 어떻게 그룹화할지 결정하는 key입니다. 대부분의 집계 메서드는 집계할 value도 지정해야 합니다. 위 예시에서 집계되는 값은 $sale->amount입니다. 이어서 sum 같은 집계 메서드를 하나 이상 호출하면, Pulse가 나중에 효율적으로 조회할 수 있도록 미리 집계된 값을 "버킷(bucket)"에 저장합니다.
사용할 수 있는 집계 메서드는 다음과 같습니다.
avgcountmaxminsum
NOTE
현재 인증된 사용자의 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 }}
@endforeachPulse는 주로 미리 집계된 버킷에서 데이터를 가져옵니다. 따라서 지정한 집계는 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(
// ...
);
}
}