Laravel Pulse

번역일: 2026년 6월 20일

Laravel Pulse

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

소개

Laravel Pulse는 애플리케이션의 성능과 사용 현황을 한눈에 파악할 수 있는 모니터링 도구입니다. Pulse를 사용하면 느린 Job이나 엔드포인트 같은 병목 지점을 찾아내고, 가장 활발한 사용자를 확인하는 등 다양한 인사이트를 얻을 수 있습니다.

개별 이벤트에 대한 심층적인 디버깅이 필요하다면 Laravel Telescope를 참고하세요.

설치

WARNING

Pulse의 기본 스토리지 구현은 현재 MySQL 또는 PostgreSQL 데이터베이스를 필요로 합니다. 다른 데이터베이스 엔진을 사용하고 있다면, Pulse 데이터 저장을 위한 별도의 MySQL 또는 PostgreSQL 데이터베이스가 필요합니다.

Pulse가 현재 베타 버전이므로, 베타 패키지 릴리스를 설치할 수 있도록 composer.json 파일을 다음과 같이 수정해야 할 수 있습니다.

"minimum-stability": "beta",
"prefer-stable": true

이후 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/AuthServiceProvider.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 클래스의 boot 메서드에서 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 레코더 문서를 참고하세요.

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 디스패치가 빈번하다면 샘플링 활성화를 고려해보세요. 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 쿼리만으로 그룹화하려면 위치 캡처를 비활성화할 수 있습니다.

자세한 내용은 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 레코더는 Exceptions 카드에 표시할 애플리케이션의 보고 가능한 예외 정보를 수집합니다.

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

Queues

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

샘플링 비율과 무시할 Job 패턴을 선택적으로 조정할 수 있습니다.

Slow Jobs

SlowJobs 레코더는 Slow Jobs 카드에 표시할 느린 Job 정보를 수집합니다.

느린 Job 임계값, 샘플링 비율, 무시할 Job 패턴을 선택적으로 조정할 수 있습니다.

Slow Outgoing Requests

SlowOutgoingRequests 레코더는 Laravel의 HTTP 클라이언트를 통해 발생한 외부 HTTP 요청 중 설정된 임계값을 초과하는 요청을 수집하여 Slow Outgoing Requests 카드에 표시합니다.

느린 외부 요청 임계값, 샘플링 비율, 무시할 URL 패턴을 선택적으로 조정할 수 있습니다.

유사한 URL을 하나의 항목으로 묶고 싶다면 URL 그룹화를 설정할 수 있습니다. 예를 들어, URL 경로에서 고유 ID를 제거하거나 도메인만으로 그룹화할 수 있습니다. 그룹은 URL의 일부를 "찾아 바꾸기"하는 정규 표현식으로 설정합니다. 설정 파일에 예시가 포함되어 있습니다.

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

첫 번째로 일치하는 패턴이 사용되며, 일치하는 패턴이 없으면 URL이 그대로 기록됩니다.

Slow Queries

SlowQueries 레코더는 설정된 임계값을 초과하는 데이터베이스 쿼리를 수집하여 Slow Queries 카드에 표시합니다.

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

Slow Requests

Requests 레코더는 Slow Requests 카드와 Application Usage 카드에 표시할 애플리케이션 요청 정보를 수집합니다.

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

Servers

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

각 서버는 고유한 이름을 가져야 합니다. 기본적으로 Pulse는 PHP의 gethostname 함수가 반환하는 값을 사용하며, PULSE_SERVER_NAME 환경 변수로 커스터마이징할 수 있습니다.

PULSE_SERVER_NAME=load-balancer

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

User Jobs

UserJobs 레코더는 Application Usage 카드에 표시할 사용자별 Job 디스패치 정보를 수집합니다.

샘플링 비율과 무시할 Job 패턴을 선택적으로 조정할 수 있습니다.

User Requests

UserRequests 레코더는 Application Usage 카드에 표시할 사용자별 요청 정보를 수집합니다.

샘플링 비율과 무시할 요청 패턴을 선택적으로 조정할 수 있습니다.

필터링

위에서 살펴본 것처럼, 많은 레코더는 설정을 통해 요청 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 Ingest

WARNING

Redis Ingest를 사용하려면 Redis 6.2 이상이 필요하며, 애플리케이션의 Redis 클라이언트 드라이버로 phpredis 또는 predis가 설정되어 있어야 합니다.

기본적으로 Pulse는 HTTP 응답이 클라이언트에 전송되거나 Job이 처리된 후에 설정된 데이터베이스 연결에 직접 데이터를 저장합니다. 대신 Redis Ingest 드라이버를 사용하면 데이터를 Redis 스트림으로 전송할 수 있습니다. PULSE_INGEST_DRIVER 환경 변수로 활성화할 수 있습니다.

PULSE_INGEST_DRIVER=redis

Pulse는 기본적으로 기본 Redis 연결을 사용하며, PULSE_REDIS_CONNECTION 환경 변수로 커스터마이징할 수 있습니다.

PULSE_REDIS_CONNECTION=pulse

Redis Ingest를 사용할 때는 pulse:work 명령어를 실행하여 스트림을 모니터링하고, Redis에서 Pulse 데이터베이스 테이블로 데이터를 이동시켜야 합니다.

php artisan pulse:work

NOTE

pulse:work 프로세스가 백그라운드에서 지속적으로 실행되도록 하려면 Supervisor 같은 프로세스 모니터를 사용하세요.

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

php artisan pulse:restart

[