Laravel Telescope

• 소개
• 설치
  • 로컬 전용 설치
  • 구성
  • 데이터 정리
  • 대시보드 권한 부여
• Telescope 업그레이드
• 필터링
  • 엔트리
  • 배치
• 태깅
• 사용 가능한 감시자
  • 배치 감시자
  • 캐시 감시자
  • 명령 감시자
  • 덤프 감시자
  • 이벤트 감시자
  • 예외 감시자
  • 게이트 감시자
  • HTTP 클라이언트 감시자
  • 작업 감시자
  • 로그 감시자
  • 메일 감시자
  • 모델 감시자
  • 알림 감시자
  • 쿼리 감시자
  • Redis 감시자
  • 요청 감시자
  • 스케줄 감시자
  • 뷰 감시자
• 사용자 아바타 표시

소개

Laravel Telescope은 로컬 Laravel 개발 환경에 훌륭한 동반자가 됩니다. Telescope는 애플리케이션으로 들어오는 요청, 예외, 로그 항목, 데이터베이스 쿼리, 큐에 대기 중인 작업, 메일, 알림, 캐시 작업, 예약된 작업, 변수 덤프 등에 대한 통찰력을 제공합니다.

설치

Composer 패키지 관리자를 사용하여 Laravel 프로젝트에 Telescope를 설치할 수 있습니다.

composer require laravel/telescope

Telescope를 설치한 후, telescope:install Artisan 명령어를 사용하여 해당 에셋과 마이그레이션을 게시하십시오. Telescope를 설치한 후에는 Telescope의 데이터를 저장하는 데 필요한 테이블을 생성하기 위해 migrate 명령어 또한 실행해야 합니다:

php artisan telescope:install
 
php artisan migrate

마지막으로, /telescope 경로를 통해 Telescope 대시보드에 접근할 수 있습니다.

로컬 전용 설치

로컬 개발을 지원하기 위해서만 Telescope를 사용하려는 경우, --dev 플래그를 사용하여 Telescope를 설치할 수 있습니다:

composer require laravel/telescope --dev
 
php artisan telescope:install
 
php artisan migrate

telescope:install을 실행한 후, 애플리케이션의 bootstrap/providers.php 설정 파일에서 TelescopeServiceProvider 서비스 제공자 등록을 제거해야 합니다. 대신, App\Providers\AppServiceProvider 클래스의 register 메서드에서 Telescope 서비스 제공자를 수동으로 등록하십시오. 제공자를 등록하기 전에 현재 환경이 local인지 확인합니다:

/**
 * Register any application services.
 */
public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

마지막으로, 다음을 composer.json 파일에 추가하여 Telescope 패키지가 자동 검색되지 않도록 해야 합니다:

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

구성

Telescope의 에셋을 게시한 후, 기본 구성 파일은 config/telescope.php에 위치하게 됩니다. 이 구성 파일을 통해 워처 옵션을 구성할 수 있습니다. 각 구성 옵션에는 해당 목적에 대한 설명이 포함되어 있으므로 이 파일을 자세히 살펴보십시오.

필요한 경우, enabled 구성 옵션을 사용하여 Telescope의 데이터 수집을 완전히 비활성화할 수 있습니다:

'enabled' => env('TELESCOPE_ENABLED', true),

데이터 정리

정리를 하지 않으면 telescope_entries 테이블에 레코드가 매우 빠르게 누적될 수 있습니다. 이를 완화하기 위해, telescope:prune Artisan 명령어를 매일 실행하도록 스케줄링해야 합니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('telescope:prune')->daily();

기본적으로 24시간이 지난 모든 항목이 정리됩니다. 명령어를 호출할 때 hours 옵션을 사용하여 Telescope 데이터를 보관할 기간을 결정할 수 있습니다. 예를 들어, 다음 명령어는 48시간 전에 생성된 모든 레코드를 삭제합니다:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('telescope:prune --hours=48')->daily();

대시보드 권한 부여

Telescope 대시보드는 /telescope 경로를 통해 접근할 수 있습니다. 기본적으로 local 환경에서만 이 대시보드에 접근할 수 있습니다. app/Providers/TelescopeServiceProvider.php 파일 내에는 권한 부여 게이트 정의가 있습니다. 이 권한 부여 게이트는 비-로컬 환경에서 Telescope에 대한 접근을 제어합니다. 필요에 따라 이 게이트를 수정하여 Telescope 설치에 대한 접근을 제한할 수 있습니다:

use App\Models\User;
 
/**
 * Telescope 게이트를 등록합니다.
 *
 * 이 게이트는 비-로컬 환경에서 누가 Telescope에 접근할 수 있는지 결정합니다.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

Telescope 업그레이드

Telescope의 새로운 주요 버전으로 업그레이드할 때는 업그레이드 가이드를 주의 깊게 검토하는 것이 중요합니다.

또한, 새로운 Telescope 버전으로 업그레이드할 때마다 Telescope의 에셋을 다시 게시해야 합니다:

php artisan telescope:publish

애셋을 최신 상태로 유지하고 향후 업데이트에서 발생할 수 있는 문제를 방지하려면 애플리케이션의 composer.json 파일에 있는 post-update-cmd 스크립트에 vendor:publish --tag=laravel-assets 명령어를 추가할 수 있습니다.

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

필터링

항목

App\Providers\TelescopeServiceProvider 클래스에 정의된 filter 클로저를 통해 Telescope에서 기록되는 데이터를 필터링할 수 있습니다. 기본적으로 이 클로저는 local 환경의 모든 데이터와 다른 모든 환경의 예외, 실패한 작업, 예약된 작업 및 모니터링된 태그가 있는 데이터를 기록합니다.

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->isSlowQuery() ||
            $entry->hasMonitoredTag();
    });
}

배치

filter 클로저가 개별 항목에 대한 데이터를 필터링하는 반면, filterBatch 메서드를 사용하여 주어진 요청 또는 콘솔 명령에 대한 모든 데이터를 필터링하는 클로저를 등록할 수 있습니다. 클로저가 true를 반환하면 모든 항목이 Telescope에 기록됩니다.

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entries->contains(function (IncomingEntry $entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

태깅

Telescope를 사용하면 "태그"로 항목을 검색할 수 있습니다. 종종 태그는 Telescope가 자동으로 항목에 추가하는 Eloquent 모델 클래스 이름 또는 인증된 사용자 ID입니다. 경우에 따라 항목에 고유한 사용자 정의 태그를 연결할 수 있습니다. 이를 수행하려면 Telescope::tag 메서드를 사용하면 됩니다. tag 메서드는 태그 배열을 반환해야 하는 클로저를 허용합니다. 클로저에서 반환된 태그는 Telescope가 자동으로 항목에 연결하는 모든 태그와 병합됩니다. 일반적으로 App\Providers\TelescopeServiceProvider 클래스의 register 메서드 내에서 tag 메서드를 호출해야 합니다.

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::tag(function (IncomingEntry $entry) {
        return $entry->type === 'request'
                    ? ['status:'.$entry->content['response_status']]
                    : [];
    });
 }

사용 가능한 감시자

Telescope "감시자"는 요청 또는 콘솔 명령이 실행될 때 애플리케이션 데이터를 수집합니다. config/telescope.php 구성 파일 내에서 활성화하려는 감시자 목록을 사용자 지정할 수 있습니다.

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

일부 감시자를 사용하면 추가 사용자 정의 옵션을 제공할 수도 있습니다.

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

배치 감시자

배치 감시자는 작업 및 연결 정보를 포함하여 대기열에 있는 배치에 대한 정보를 기록합니다.

캐시 감시자

캐시 감시자는 캐시 키가 적중, 누락, 업데이트 및 삭제될 때 데이터를 기록합니다.

명령 감시자

명령 감시자는 Artisan 명령이 실행될 때마다 인수, 옵션, 종료 코드 및 출력을 기록합니다. 감시자가 기록하는 특정 명령을 제외하려면 config/telescope.php 파일 내의 ignore 옵션에서 명령을 지정할 수 있습니다.

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

덤프 감시자

덤프 감시자는 Telescope에서 변수 덤프를 기록하고 표시합니다. Laravel을 사용하는 경우 전역 dump 함수를 사용하여 변수를 덤프할 수 있습니다. 덤프를 기록하려면 덤프 감시자 탭이 브라우저에서 열려 있어야 합니다. 그렇지 않으면 덤프가 감시자에 의해 무시됩니다.

이벤트 감시자

이벤트 감시자는 애플리케이션에서 디스패치한 모든 이벤트에 대한 페이로드, 리스너 및 브로드캐스트 데이터를 기록합니다. Laravel 프레임워크의 내부 이벤트는 이벤트 감시자에서 무시됩니다.

예외 감시자

예외 감시자는 애플리케이션에서 발생하는 보고 가능한 예외에 대한 데이터 및 스택 추적을 기록합니다.

게이트 감시자

게이트 감시자는 애플리케이션의 게이트 및 정책 검사의 데이터 및 결과를 기록합니다. 감시자가 기록하는 특정 능력을 제외하려면 config/telescope.php 파일의 ignore_abilities 옵션에서 지정할 수 있습니다.

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

HTTP 클라이언트 감시자

HTTP 클라이언트 감시자는 애플리케이션에서 수행한 발신 HTTP 클라이언트 요청을 기록합니다.

작업 감시자

작업 감시자는 애플리케이션에서 디스패치한 모든 작업의 데이터와 상태를 기록합니다.

로그 감시자

로그 감시자는 애플리케이션에서 작성한 모든 로그에 대한 로그 데이터를 기록합니다.

기본적으로 Telescope는 error 수준 이상의 로그만 기록합니다. 그러나 애플리케이션의 config/telescope.php 구성 파일에서 level 옵션을 수정하여 이 동작을 수정할 수 있습니다.

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],
 
    // ...
],

메일 감시자

메일 감시자를 사용하면 애플리케이션에서 보낸 이메일의 브라우저 내 미리보기와 관련 데이터를 볼 수 있습니다. 이메일을 .eml 파일로 다운로드할 수도 있습니다.

모델 감시자

모델 감시자는 Eloquent 모델 이벤트가 디스패치될 때마다 모델 변경 사항을 기록합니다. 감시자의 events 옵션을 통해 기록해야 하는 모델 이벤트를 지정할 수 있습니다.

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

주어진 요청 중에 하이드레이션된 모델 수를 기록하려면 hydrations 옵션을 활성화합니다.

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
        'hydrations' => true,
    ],
    ...
],

알림 감시자

알림 감시자는 애플리케이션에서 보낸 모든 알림을 기록합니다. 알림이 이메일을 트리거하고 메일 감시자가 활성화된 경우 메일 감시자 화면에서 이메일을 미리 볼 수도 있습니다.

쿼리 감시자

쿼리 감시자는 애플리케이션에서 실행되는 모든 쿼리에 대한 원시 SQL, 바인딩 및 실행 시간을 기록합니다. 또한 감시자는 100밀리초보다 느린 모든 쿼리에 slow 태그를 지정합니다. 감시자의 slow 옵션을 사용하여 느린 쿼리 임계값을 사용자 지정할 수 있습니다.

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redis 감시자

Redis 감시자는 애플리케이션에서 실행되는 모든 Redis 명령을 기록합니다. Redis를 캐싱에 사용하는 경우 캐시 명령도 Redis 감시자에 의해 기록됩니다.

요청 감시자

요청 감시자는 애플리케이션에서 처리하는 모든 요청과 관련된 요청, 헤더, 세션 및 응답 데이터를 기록합니다. size_limit (킬로바이트) 옵션을 통해 기록된 응답 데이터를 제한할 수 있습니다.

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

스케줄 감시자

스케줄 감시자는 애플리케이션에서 실행하는 모든 예약된 작업의 명령 및 출력을 기록합니다.

뷰 감시자

뷰 감시자는 뷰를 렌더링할 때 사용되는 뷰 이름, 경로, 데이터 및 "컴포저"를 기록합니다.

사용자 아바타 표시

Telescope 대시보드는 주어진 항목이 저장되었을 때 인증된 사용자의 사용자 아바타를 표시합니다. 기본적으로 Telescope는 Gravatar 웹 서비스를 사용하여 아바타를 검색합니다. 그러나 App\Providers\TelescopeServiceProvider 클래스에서 콜백을 등록하여 아바타 URL을 사용자 지정할 수 있습니다. 콜백은 사용자의 ID와 이메일 주소를 받고 사용자의 아바타 이미지 URL을 반환해야 합니다.

use App\Models\User;
use Laravel\Telescope\Telescope;
 
/**
 * Register any application services.
 */
public function register(): void
{
    // ...
 
    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}