Laravel Pulse

번역일: 2026년 6월 21일

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 migrate

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

NOTE

Pulse 데이터를 애플리케이션의 기본 데이터베이스가 아닌 별도 데이터베이스에 저장하려면 전용 데이터베이스 연결 설정을 참고하세요.

설정

Pulse의 주요 설정 옵션 대부분은 환경 변수로 제어할 수 있습니다. 사용 가능한 옵션 확인, 새 레코더 등록, 고급 옵션 설정이 필요하다면 config/pulse.php 설정 파일을 퍼블리시하세요:

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

대시보드

접근 권한

Pulse 대시보드는 /pulse 라우트로 접근합니다. 기본적으로 local 환경에서만 접근 가능하므로, 프로덕션 환경에서는 'viewPulse' 권한 게이트를 커스터마이징해야 합니다. app/Providers/AppServiceProvider.php 파일의 boot 메서드에서 설정합니다:

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만 기록합니다. 대시보드를 렌더링할 때 기본 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 명령어가 실행 중인 모든 서버의 시스템 리소스 사용량을 표시합니다. 시스템 리소스 모니터링에 대한 자세한 내용은 서버 레코더 문서를 참고하세요.

인프라에서 서버를 교체한 경우, 일정 시간이 지난 후 비활성 서버를 대시보드에서 숨기고 싶을 수 있습니다. ignore-after prop에 초 단위 숫자를 지정하면 해당 시간 이후 비활성 서버가 대시보드에서 제거됩니다. 1 hour나 3 days and 1 hour처럼 상대적 시간 문자열도 사용할 수 있습니다:

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

애플리케이션 사용 현황 (Application Usage)

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

모든 사용 현황 지표를 동시에 확인하려면 카드를 여러 번 포함하고 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 /> 카드는 애플리케이션 큐의 처리량을 보여줍니다. 큐에 추가됨, 처리 중, 처리 완료, 릴리즈됨, 실패한 Job 수를 확인할 수 있습니다. 자세한 내용은 큐 레코더 문서를 참고하세요.

느린 요청 (Slow Requests)

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

느린 Job (Slow Jobs)

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

느린 쿼리 (Slow Queries)

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

기본적으로 SQL 쿼리(바인딩 제외)와 발생 위치를 기준으로 그룹화됩니다. SQL 쿼리만으로 그룹화하려면 위치 캡처를 비활성화할 수도 있습니다.

매우 긴 SQL 쿼리의 구문 강조로 인해 렌더링 성능 문제가 발생한다면 without-highlighting prop을 추가하여 강조 표시를 비활성화하세요:

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

자세한 내용은 느린 쿼리 레코더 문서를 참고하세요.

느린 외부 요청 (Slow Outgoing Requests)

<livewire:pulse.slow-outgoing-requests /> 카드는 Laravel의 HTTP 클라이언트를 통해 발생한 외부 HTTP 요청 중 설정된 임계값(기본값 1,000ms)을 초과한 항목을 표시합니다.

기본적으로 전체 URL을 기준으로 그룹화되지만, 정규 표현식을 사용해 유사한 URL을 하나로 묶을 수도 있습니다. 자세한 내용은 느린 외부 요청 레코더 문서를 참고하세요.

캐시 (Cache)

<livewire:pulse.cache /> 카드는 전체 및 개별 키 단위의 캐시 히트/미스 통계를 표시합니다.

기본적으로 키를 기준으로 그룹화되지만, 정규 표현식으로 유사한 키를 묶을 수도 있습니다. 자세한 내용은 캐시 인터랙션 레코더 문서를 참고하세요.

데이터 수집

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

php artisan pulse:check

NOTE

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

pulse:check는 장기 실행 프로세스이므로 코드베이스 변경 사항을 재시작 없이는 반영하지 못합니다. 애플리케이션 배포 과정에서 pulse:restart 명령어를 호출하여 안전하게 재시작하세요:

php artisan pulse:restart

NOTE

Pulse는 재시작 신호를 저장하기 위해 캐시를 사용합니다. 이 기능을 사용하기 전에 캐시 드라이버가 올바르게 설정되어 있는지 확인하세요.

레코더

레코더는 애플리케이션의 데이터를 수집하여 Pulse 데이터베이스에 기록하는 역할을 합니다. 레코더는 Pulse 설정 파일의 recorders 섹션에서 등록하고 설정합니다.

캐시 인터랙션 (CacheInteractions)

CacheInteractions 레코더는 애플리케이션에서 발생하는 캐시 히트/미스 정보를 수집하여 캐시 카드에 표시합니다.

샘플링 비율 조정과 무시할 키 패턴을 설정할 수 있습니다.

유사한 키를 하나의 항목으로 묶는 키 그룹화를 설정할 수도 있습니다. 예를 들어 동일한 유형의 정보를 캐싱하는 키에서 고유 ID를 제거할 수 있습니다. 그룹은 키의 일부를 "찾아 바꾸기"하는 정규 표현식으로 설정합니다. 설정 파일에 예시가 포함되어 있습니다:

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

가장 먼저 매칭되는 패턴이 사용됩니다. 매칭되는 패턴이 없으면 키가 그대로 기록됩니다.

예외 (Exceptions)

Exceptions 레코더는 애플리케이션에서 보고 가능한 예외 정보를 수집하여 예외 카드에 표시합니다.

샘플링 비율 조정, 무시할 예외 패턴 설정, 예외 발생 위치 캡처 여부를 설정할 수 있습니다. 발생 위치는 대시보드에 표시되어 예외 원인을 추적하는 데 도움이 됩니다. 단, 동일한 예외가 여러 위치에서 발생하면 각 고유 위치마다 별도로 표시됩니다.

큐 (Queues)

Queues 레코더는 애플리케이션의 큐 정보를 수집하여 큐 카드에 표시합니다.

샘플링 비율 조정과 무시할 Job 패턴을 설정할 수 있습니다.

느린 Job (SlowJobs)

SlowJobs 레코더는 애플리케이션에서 발생하는 느린 Job 정보를 수집하여 느린 Job 카드에 표시합니다.

느린 Job 임계값, 샘플링 비율, 무시할 Job 패턴을 설정할 수 있습니다.

특정 Job은 다른 Job보다 더 오래 걸릴 것으로 예상되는 경우, Job별 임계값을 설정할 수 있습니다:

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

Job 클래스명에 매칭되는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.

느린 외부 요청 (SlowOutgoingRequests)

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)

SlowQueries 레코더는 애플리케이션에서 설정된 임계값을 초과한 데이터베이스 쿼리를 수집하여 느린 쿼리 카드에 표시합니다.

느린 쿼리 임계값, 샘플링 비율, 무시할 쿼리 패턴을 설정할 수 있습니다. 쿼리 발생 위치 캡처 여부도 설정 가능합니다. 발생 위치는 대시보드에 표시되어 쿼리 원인을 추적하는 데 도움이 됩니다. 단, 동일한 쿼리가 여러 위치에서 실행되면 각 고유 위치마다 별도로 표시됩니다.

특정 쿼리는 다른 쿼리보다 더 오래 걸릴 것으로 예상되는 경우, 쿼리별 임계값을 설정할 수 있습니다:

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

쿼리 SQL에 매칭되는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.

느린 요청 (Slow Requests)

Requests 레코더는 애플리케이션에 들어오는 요청 정보를 수집하여 느린 요청 카드와 애플리케이션 사용 현황 카드에 표시합니다.

느린 라우트 임계값, 샘플링 비율, 무시할 경로를 설정할 수 있습니다.

특정 요청은 다른 요청보다 더 오래 걸릴 것으로 예상되는 경우, 요청별 임계값을 설정할 수 있습니다:

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

요청 URL에 매칭되는 정규 표현식 패턴이 없으면 'default' 값이 사용됩니다.

서버 (Servers)

Servers 레코더는 애플리케이션을 구동하는 서버의 CPU, 메모리, 저장소 사용량을 수집하여 서버 카드에 표시합니다. 이 레코더는 모니터링할 각 서버에서 pulse:check 명령어가 실행 중이어야 합니다.

각 서버는 고유한 이름을 가져야 합니다. Pulse는 기본적으로 PHP의 gethostname 함수가 반환하는 값을 사용합니다. 변경하려면 PULSE_SERVER_NAME 환경 변수를 설정하세요:

PULSE_SERVER_NAME=load-balancer

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

사용자 Job (UserJobs)

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

샘플링 비율 조정과 무시할 Job 패턴을 설정할 수 있습니다.

사용자 요청 (UserRequests)

UserRequests 레코더는 애플리케이션에 요청을 보내는 사용자 정보를 수집하여 애플리케이션 사용 현황 카드에 표시합니다.

샘플링 비율 조정과 무시할 URL 패턴을 설정할 수 있습니다.

필터링

앞서 살펴본 것처럼 많은 레코더는 요청 URL 등 값을 기반으로 항목을 "무시"하는 설정을 제공합니다. 그러나 현재 인증된 사용자처럼 다른 요인을 기준으로 레코드를