Laravel Pulse

번역일: 2026년 6월 25일

Laravel Pulse

소개
설치
- 설정
대시보드
데이터 수집
- 리코더
- 필터링
성능
커스텀 카드

소개

Laravel 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 migrate

마이그레이션이 완료되면 /pulse 라우트로 Pulse 대시보드에 접근할 수 있습니다.

NOTE

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

설정

Pulse의 많은 설정 옵션은 환경 변수로 제어할 수 있습니다. 사용 가능한 옵션을 확인하거나, 새로운 리코더를 등록하거나, 고급 옵션을 설정하려면 config/pulse.php 설정 파일을 퍼블리시하세요:

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

대시보드

접근 권한

Pulse 대시보드는 /pulse 라우트를 통해 접근합니다. 기본적으로 local 환경에서만 접근할 수 있으므로, 운영(production) 환경에서는 '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 />

사용자 정보 조회

Application Usage 카드처럼 사용자 정보를 표시하는 카드의 경우, Pulse는 사용자 ID만 기록합니다. 대시보드를 렌더링할 때 기본 Authenticatable 모델에서 name과 email 필드를 조회하며, 아바타는 Gravatar 서비스를 통해 표시합니다.

App\Providers\AppServiceProvider 클래스에서 Pulse::user 메서드를 호출하면 표시 필드와 아바타를 커스터마이징할 수 있습니다.

user 메서드는 Authenticatable 모델을 인자로 받는 클로저를 받으며, 클로저는 name, extra, avatar 정보를 포함한 배열을 반환해야 합니다:

use Laravel\Pulse\Facades\Pulse;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);

    // ...
}

NOTE

Laravel\Pulse\Contracts\ResolvesUsers 컨트랙트를 구현하고 Laravel의 서비스 컨테이너에 바인딩하면 인증된 사용자를 수집하고 조회하는 방식을 완전히 커스터마이징할 수 있습니다.

카드

Servers

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

인프라에서 서버를 교체한 경우, 비활성 서버가 일정 시간 후 대시보드에서 사라지도록 설정할 수 있습니다. ignore-after 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" />

사용자 정보 조회 및 표시 방법 커스터마이징은 사용자 정보 조회 문서를 참고하세요.

NOTE

애플리케이션이 많은 요청을 받거나 Job을 대량으로 디스패치한다면 샘플링을 활성화하는 것이 좋습니다. 자세한 내용은 user requests 리코더, user jobs 리코더, slow jobs 리코더 문서를 확인하세요.

Exceptions

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

Queues

<livewire:pulse.queues /> 카드는 애플리케이션 큐의 처리량을 보여주며, 대기 중, 처리 중, 처리 완료, 반환됨, 실패한 Job의 수를 포함합니다. 자세한 내용은 queues 리코더 문서를 참고하세요.

Slow Requests

<livewire:pulse.slow-requests /> 카드는 설정된 임계값(기본값: 1,000ms)을 초과하는 요청을 표시합니다. 자세한 내용은 slow requests 리코더 문서를 참고하세요.

Slow Jobs

<livewire:pulse.slow-jobs /> 카드는 설정된 임계값(기본값: 1,000ms)을 초과하는 큐 Job을 표시합니다. 자세한 내용은 slow jobs 리코더 문서를 참고하세요.

Slow Queries

<livewire:pulse.slow-queries /> 카드는 설정된 임계값(기본값: 1,000ms)을 초과하는 데이터베이스 쿼리를 표시합니다.

기본적으로 SQL 쿼리(바인딩 제외)와 발생 위치를 기준으로 그룹화됩니다. SQL 쿼리만을 기준으로 그룹화하고 싶다면 위치 정보 수집을 비활성화할 수 있습니다.

매우 긴 SQL 쿼리의 신택스 하이라이팅으로 인해 렌더링 성능 문제가 발생한다면, without-highlighting prop으로 하이라이팅을 비활성화할 수 있습니다:

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

자세한 내용은 slow queries 리코더 문서를 참고하세요.

Slow Outgoing Requests

<livewire:pulse.slow-outgoing-requests /> 카드는 Laravel의 HTTP 클라이언트를 사용해 보내는 외부 요청 중 설정된 임계값(기본값: 1,000ms)을 초과하는 것들을 표시합니다.

기본적으로 전체 URL을 기준으로 그룹화됩니다. 정규식을 활용해 유사한 외부 요청을 정규화하거나 그룹화할 수도 있습니다. 자세한 내용은 slow outgoing requests 리코더 문서를 참고하세요.

Cache

<livewire:pulse.cache /> 카드는 애플리케이션의 캐시 히트 및 미스 통계를 전체와 개별 키 기준으로 보여줍니다.

기본적으로 키를 기준으로 그룹화됩니다. 정규식을 활용해 유사한 키를 정규화하거나 그룹화할 수도 있습니다. 자세한 내용은 cache interactions 리코더 문서를 참고하세요.

데이터 수집

대부분의 Pulse 리코더는 Laravel이 디스패치하는 프레임워크 이벤트를 기반으로 자동으로 데이터를 수집합니다. 그러나 servers 리코더와 일부 서드파티 카드는 주기적으로 정보를 폴링해야 합니다. 이런 카드를 사용하려면 모든 애플리케이션 서버에서 pulse:check 데몬을 실행해야 합니다:

php artisan pulse:check

NOTE

pulse:check 프로세스를 백그라운드에서 지속적으로 실행하려면 Supervisor 같은 프로세스 모니터를 사용해 명령어가 중단되지 않도록 관리하세요.

pulse:check는 장시간 실행되는 프로세스이므로, 코드베이스 변경 사항을 반영하려면 재시작이 필요합니다. 배포 과정에서 pulse:restart 명령어를 호출해 부드럽게 재시작하세요:

php artisan pulse:restart

NOTE

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별 임계값을 설정할 수 있습니다:

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 경로에서 고유 ID를 제거하거나 도메인별로 그룹화할 수 있습니다. 설정 파일에 몇 가지 예시가 포함되어 있습니다:

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-balancer

Pulse 설정 파일에서 모니터링할 디렉터리도 커스터마이징할 수 있습니다.

User Jobs

UserJobs 리코더는 애플리케이션에서 Job을 디스패치하는 사용자 정보를 수집해 Application Usage 카드에 표시합니다.

샘플 레이트와 무시할 Job 패턴을 선택적으로 조정할 수 있습니다.

User Requests

UserRequests 리코더는 애플리케이션에 요청을 보내는 사용자 정보를 수집해 Application Usage 카드에 표시합니다.

샘플 레이트와 무시할 URL 패턴을 선택적으로 조정할 수 있습니다.

필터링

앞서 살펴본 것처럼, 많은 리코더는 설정을 통해 요청 URL 등 특정 값을 기준으로 수집 항목을 "무시"할 수 있습니다. 하지만 현재 인증된 사용자처럼 다른 조건을 기준으로 레코드를 필터링하고 싶을 때도 있습니다. 이 경우 Pulse의 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는 추가 인프라 없이도 기존 애플리케이션에 바로 적용할 수 있