이 가이드는 Pulse 1.11.0의 소스 코드를 바탕으로 합니다. 예제의
ReportGenerated 이벤트는 설명을 위한 가상의 클래스입니다. 실제 패키지에서는 자신의 이벤트로 바꿔 사용하세요.처리 흐름
레코더는 이벤트를 받으면 Pulse의 버퍼에 기록을 쌓습니다. 버퍼는 수집(ingest) 시점에 한꺼번에 저장됩니다.레코더 만들기
레코더는listen 프로퍼티에 구독할 이벤트를 선언하고, record() 메서드에 처리를 구현합니다. 아래 예제는 패키지가 디스패치하는 ReportGenerated 이벤트를 기록합니다. 이벤트는 $type과 $durationMs 프로퍼티를 가진다고 가정합니다.
Ignores와 Sampling 트레이트는 아래에서 설명하는 ignore와 sample_rate 설정을 읽습니다.
애플리케이션에 레코더 등록하기
애플리케이션의config/pulse.php에 있는 recorders 배열에 레코더를 등록합니다. 레코더의 클래스 이름을 키로 사용하고, 값으로 활성화 플래그와 설정을 지정합니다.
PulseServiceProvider는 pulse.enabled가 켜져 있을 때 pulse.recorders를 읽어 레코더를 등록합니다. enabled가 false인 레코더는 등록되지 않습니다. 이 설정을 패키지에서 자동으로 다시 쓰기보다는 설치 안내에 설정 예시를 보여 주는 편이 안전합니다.
집계의 종류
Pulse::record()는 Entry를 반환합니다. count(), min(), max(), sum(), avg()를 체이닝하면 해당 집계가 pulse_aggregates에 저장됩니다.
min(), max(), sum(), avg()는 계산에 value를 사용합니다. count()만 사용할 때는 value가 필요 없습니다.
이벤트가 매우 자주 발생하는 경우 onlyBuckets()로 pulse_entries의 행 수를 줄일 수 있습니다.
문자열 값 저장하기
숫자를 집계하는 대신 최신 상태와 같은 문자열을 저장하고 싶을 때는Pulse::set()을 사용합니다. 값은 pulse_values 테이블에 저장됩니다.
value는 string으로 전달해야 합니다.
무거운 처리 지연시키기
Pulse::lazy()에 전달한 클로저는 즉시 실행되지 않습니다. Pulse가 데이터를 수집할 때 실행됩니다. 기록에 시간이 걸려 응답을 보낸 뒤에 실행하고 싶을 때 사용합니다.
인증된 사용자 기록하기
인증된 사용자의 식별자가 필요할 때는Pulse::resolveAuthenticatedUserId()를 사용합니다. 인증된 사용자가 없으면 null을 반환합니다.
제외, 샘플링, 필터
기록되는 양을 줄이려면 다음 네 가지를 사용합니다.ignore설정:shouldIgnore()에 전달한 값이 정규 표현식 중 하나와 일치하면 기록을 건너뜁니다. 위 예제에서는$event->type이/^debug_/와 일치하는 이벤트를 건너뜁니다.sample_rate설정:shouldSample()이 확인합니다.1은 모든 이벤트를 기록하고,0.1은 약 10%를 기록합니다.Pulse::ignore(): 콜백 안에서의 기록을 비활성화하고 콜백의 결과를 반환합니다.Pulse::filter(): 저장 전에 각Entry또는Value를 받아true를 반환한 항목만 저장합니다.
예외 처리
Pulse는 레코더의 처리와 수집을rescue()로 감쌉니다. 레코더 안에서 던져진 예외는 애플리케이션까지 전달되지 않습니다. handleExceptionsUsing()이 설정되어 있지 않으면 예외는 조용히 버려집니다. 예외를 보고하려면 애플리케이션에서 설정합니다.
테스트
레코더를 테스트하려면 이벤트를 디스패치하고Pulse::ingest()를 호출한 뒤 저장된 행을 확인할 수 있습니다. 아래 예제는 Pulse의 소스 코드에서 도출한 것이며 실행해 보지는 않았습니다. 테스트 환경에서 pulse.enabled가 켜져 있는지 확인하세요.
키 설계
key는 집계의 단위입니다. 사용자 ID나 URL처럼 끝없이 늘어나는 값을 사용하면 데이터 양이 늘어나고 집계를 읽기 어려워집니다. key에는 이벤트 종류나 프로세스 이름처럼 종류가 한정된 값을 사용하세요.