메인 콘텐츠로 건너뛰기

Laravel Pulse란

Laravel Pulse는 애플리케이션의 성능과 사용 상황을 한눈에 파악할 수 있는 모니터링 대시보드입니다. 느린 잡이나 느린 엔드포인트의 병목을 특정하거나, 가장 액티브한 사용자를 조사할 수 있습니다.

Telescope와 Pulse의 차이

특징Laravel PulseLaravel Telescope
목적앱 전체의 경향·집계 데이터를 모니터링개별 리퀘스트·이벤트의 상세 디버그
데이터집계된 메트릭개별 이벤트의 로그
적합한 장면프로덕션 환경의 성능 모니터링개발·스테이징 환경에서의 디버그
개별 이벤트의 상세 디버그에는 Laravel Telescope를 사용해 주세요.

데이터 플로우 도


설치

Pulse의 1st-party 스토리지 구현은 MySQL, MariaDB, 또는 PostgreSQL 데이터베이스가 필요합니다. 다른 데이터베이스 엔진을 사용하고 있는 경우, Pulse 데이터 전용으로 MySQL, MariaDB, 또는 PostgreSQL 데이터베이스를 준비해 주세요.
1

패키지 설치

Composer를 사용해 Pulse를 설치합니다.
composer require laravel/pulse
2

설정 파일과 마이그레이션 공개

vendor:publish Artisan 명령으로 파일을 공개합니다.
php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
3

마이그레이션 실행

Pulse의 데이터를 저장하는 테이블을 생성합니다.
php artisan migrate
마이그레이션 완료 후, /pulse 라우트에서 대시보드에 접근할 수 있습니다.

설정 파일 공개

설정 파일을 별도로 공개하여 커스터마이즈할 수도 있습니다.
php artisan vendor:publish --tag=pulse-config

대시보드 접근

인증 설정

기본적으로 local 환경에서만 대시보드에 접근할 수 있습니다. 프로덕션 환경에서는 viewPulse 인증 게이트를 커스터마이즈하여 접근 제어를 설정해 주세요.
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();
    });
}
app/Providers/AppServiceProvider.phpboot 메서드에 위의 코드를 추가합니다.

대시보드 커스터마이즈

대시보드의 뷰를 공개해 카드나 레이아웃을 커스터마이즈할 수 있습니다.
php artisan vendor:publish --tag=pulse-dashboard
공개 후, resources/views/vendor/pulse/dashboard.blade.php를 편집합니다. 대시보드는 Livewire로 동작하고 있기 때문에, JavaScript의 빌드 없이 커스터마이즈할 수 있습니다.
{{-- 전폭 표시로 하기 --}}
<x-pulse full-width>
    ...
</x-pulse>

{{-- 컬럼 수를 변경 --}}
<x-pulse cols="16">
    ...
</x-pulse>
각 카드는 colsrows 프로퍼티로 크기와 위치를 조정할 수 있습니다.
<livewire:pulse.usage cols="4" rows="2" />
<livewire:pulse.slow-queries expand />

레코더

레코더는 애플리케이션의 이벤트를 캡처해 Pulse 데이터베이스에 기록합니다. 설정은 config/pulse.phprecorders 섹션에서 관리합니다.

Requests / Slow Requests

Requests 레코더는 애플리케이션에의 리퀘스트 정보를 캡처합니다. 느린 라우트의 임계값(기본값: 1000ms), 샘플링 레이트, 무시할 경로를 설정할 수 있습니다.
Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

Slow Jobs

SlowJobs 레코더는 임계값을 넘은 느린 잡을 캡처합니다(기본값: 1000ms). 잡별로 다른 임계값을 설정할 수 있습니다.
Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

Exceptions

Exceptions 레코더는 애플리케이션에서 발생한 리포트 가능한 예외를 캡처합니다. 예외 클래스와 발생 장소로 그룹화됩니다.

Cache

CacheInteractions 레코더는 캐시의 히트와 미스를 캡처합니다. 유사한 키를 그룹화하는 정규 표현식도 설정할 수 있습니다.
Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        '/:\d+/' => ':*',
    ],
],

Queues

Queues 레코더는 큐 내의 잡의 처리량(큐잉됨, 처리 중, 처리 완료, 릴리스, 실패)을 캡처합니다.

Servers

Servers 레코더는 애플리케이션을 구동하는 서버의 CPU, 메모리, 스토리지 사용량을 캡처합니다. 이 레코더를 사용하려면 모니터링 대상의 각 서버에서 pulse:check 명령을 상시 실행해야 합니다.
php artisan pulse:check
서버명은 기본적으로 PHP의 gethostname()의 값이 사용됩니다. 커스터마이즈하려면 환경 변수를 설정합니다.
PULSE_SERVER_NAME=load-balancer

Users

UserRequestsUserJobs 레코더는 리퀘스트나 잡을 송신한 사용자 정보를 캡처하여 “Application Usage” 카드에 표시합니다.

Redis Ingest

높은 트래픽 환경에서는 엔트리를 Redis 스트림에 송신한 후 데이터베이스에 가져오는 방법을 이용할 수 있습니다.
PULSE_INGEST_DRIVER=redis
Redis 인제스트를 사용하는 경우, pulse:work 명령으로 스트림을 감시해야 합니다.
php artisan pulse:work

샘플링

높은 트래픽 환경에서는 모든 이벤트를 캡처하면 데이터베이스에 수백만 행이 축적될 가능성이 있습니다. 샘플링을 활성화하면 일부 이벤트만 기록하고, 대시보드에서 근사값으로 표시합니다.
// config/pulse.php
Recorders\UserRequests::class => [
    'sample_rate' => 0.1, // 10%의 리퀘스트만 기록
],
대시보드에서는 근사값 앞에 ~가 표시됩니다. 메트릭의 엔트리 수가 많을수록, 정확도를 유지하면서 샘플링 레이트를 낮출 수 있습니다.

환경 변수

주요 설정은 환경 변수로 제어할 수 있습니다.
환경 변수설명기본값
PULSE_ENABLEDPulse 활성/비활성true
PULSE_DB_CONNECTIONPulse가 사용하는 DB 커넥션앱의 기본값
PULSE_INGEST_DRIVER인제스트 드라이버 (redis 등)storage
PULSE_SERVER_NAME서버 식별명gethostname()의 값
PULSE_SLOW_REQUESTS_THRESHOLD느린 리퀘스트의 임계값(ms)1000
PULSE_SLOW_JOBS_THRESHOLD느린 잡의 임계값(ms)1000
PULSE_SLOW_QUERIES_THRESHOLD느린 쿼리의 임계값(ms)1000

커스텀 카드

독자적인 Pulse 카드를 작성해, 애플리케이션 고유의 데이터를 표시할 수 있습니다. 카드는 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');
    }
}
카드의 뷰에서는 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>
커스텀 데이터의 캡처에는 Pulse::record 메서드를 사용합니다.
use Laravel\Pulse\Facades\Pulse;

Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();
작성한 컴포넌트는 대시보드 뷰에 포함시킵니다.
<x-pulse>
    ...
    <livewire:pulse.top-sellers cols="4" />
</x-pulse>

정리

하고 싶은 일방법
Pulse 설치composer require laravel/pulse
대시보드 접근/pulse 라우트
프로덕션 환경에서 접근 제어viewPulse 게이트 정의
서버 모니터링 활성화php artisan pulse:check를 상시 기동
샘플링 설정sample_rate 옵션으로 비율 지정

다음 단계

에러 핸들링

애플리케이션의 예외 처리와 리포트의 구조를 배웁니다.

로깅

Laravel의 로그 시스템의 설정과 활용 방법을 설명합니다.
마지막 수정일 2026년 7월 13일