Laravel Debugbar로 중복 쿼리 잡기, 설치부터 실전 활용까지

Laravel로 개발할 때 가장 먼저 까는 패키지를 하나만 고르라면 나는 Laravel Debugbar를 고른다. 에러 페이지, 뷰, 세션, 쿠키, 실행된 쿼리까지 한 화면에서 볼 수 있다. 특히 중복 쿼리를 잡을 때 많이 쓴다.

설치

composer require barryvdh/laravel-debugbar --dev

--dev를 반드시 붙인다. 개발 의존성으로 설치해야 운영 배포 시 composer install --no-dev 에서 빠진다.

# .env
APP_DEBUG=true
DEBUGBAR_ENABLED=true

Laravel 5.5 이상은 패키지 자동 등록(auto-discovery)이 되므로 config/app.php에 프로바이더를 수동으로 추가할 필요가 없다. APP_DEBUG=true 면 자동으로 켜진다.

설정을 커스텀하고 싶으면 설정 파일을 퍼블리시한다.

php artisan vendor:publish --provider="Barryvdh\Debugbar\ServiceProvider"

실전 1: N+1 쿼리 잡기

Debugbar를 쓰는 가장 큰 이유다. Queries 탭에 실행된 쿼리 수가 뜨는데, 목록 화면 하나에 쿼리가 수십 개 찍혀 있으면 십중팔구 N+1이다.

// 게시글 20개를 뿌리면서 각 글의 작성자 이름을 출력
$posts = Post::latest()->take(20)->get();

// 뷰에서 $post->user->name 접근
// → 쿼리 1(게시글) + 20(작성자) = 21개

Debugbar에 21개가 찍힌다. 해결은 eager loading이다.

$posts = Post::with('user')->latest()->take(20)->get();
// → 쿼리 2개로 줄어든다

같은 쿼리가 반복되는 건 Debugbar가 중복 쿼리를 묶어서 표시해주기 때문에 눈에 잘 띈다. 파라미터만 다른 동일 쿼리가 줄줄이 있으면 그게 신호다.

N+1을 아예 막고 싶다면

Laravel 8.43+ 에는 lazy loading 자체를 막는 옵션이 있다.

// app/Providers/AppServiceProvider.php
public function boot()
{
    Model::preventLazyLoading(! app()->isProduction());
}

개발 환경에서 eager loading을 안 걸고 관계에 접근하면 예외가 발생한다. 실수를 배포 전에 잡을 수 있어서 유용하다.

실전 2: 느린 쿼리 찾기

Queries 탭에는 각 쿼리의 실행 시간이 밀리초로 표시된다. 정렬해서 보면 어느 쿼리가 시간을 먹는지 바로 나온다.

여기서 나온 쿼리를 복사해서 EXPLAIN을 붙여 실행하면 인덱스를 타는지 확인할 수 있다. Debugbar에는 쿼리를 그대로 복사하는 버튼이 있어서 바인딩된 값까지 채워진 완성 쿼리를 얻을 수 있다.

실전 3: 어느 뷰가 렌더링됐는지 확인

Views 탭에는 렌더링된 블레이드 파일 목록과 각각에 전달된 데이터가 나온다. 컴포넌트가 중첩돼서 어느 파일이 실제로 그려지는지 헷갈릴 때 유용하다.

전달 데이터가 큰 컬렉션이면 Debugbar 자체가 느려질 수 있는데, 이럴 때는 설정에서 데이터 수집을 끌 수 있다.

// config/debugbar.php
'collectors' => [
    'views' => false,
],

실전 4: 코드 안에서 값 찍기

dd()는 실행을 멈추기 때문에 API나 리다이렉트 흐름에서는 쓰기 곤란하다. Debugbar는 흐름을 끊지 않고 값을 남길 수 있다.

Debugbar::info($order);
Debugbar::warning('재고 부족');
Debugbar::error($exception);

// 구간 측정
Debugbar::startMeasure('render', '외부 API 호출');
$result = $client->get(...);
Debugbar::stopMeasure('render');

찍은 값은 Messages 탭에, 측정 구간은 Timeline 탭에 나타난다. 특히 startMeasure는 병목이 DB인지 외부 API인지 가를 때 유용하다.

주의: 운영에 절대 켜두면 안 된다

Debugbar는 쿼리, 세션, 환경 변수, 스택 트레이스를 전부 노출한다. 운영에서 켜져 있으면 심각한 정보 유출이다.

• --dev로 설치하고 배포 시 composer install --no-dev
• 운영 .env에서 APP_DEBUG=false
• 확실히 하려면 DEBUGBAR_ENABLED=false 도 명시

APP_DEBUG를 켜둔 채 배포된 사이트가 생각보다 많다. 배포 파이프라인에 이 값을 검증하는 단계를 하나 넣어두면 마음이 편하다.

API 개발 중이라면

JSON 응답에는 Debugbar 툴바가 안 뜬다. 이럴 때는 응답 헤더로 데이터를 받는 방식이 있다.

// config/debugbar.php
'inject' => false,
'capture_ajax' => true,

브라우저 개발자 도구의 Network 탭에서 phpdebugbar 헤더를 확인하거나, Debugbar가 제공하는 별도 뷰어 URL로 접근할 수 있다. Laravel Telescope를 쓰는 것도 대안이다.

정리

• composer require barryvdh/laravel-debugbar --dev 한 줄이면 끝
• 가장 큰 효용은 N+1과 중복 쿼리 발견
• preventLazyLoading()으로 아예 예방하는 것도 방법
• Debugbar::info(), startMeasure()로 흐름 안 끊고 디버깅
• 운영에서는 반드시 꺼야 한다. 안 그러면 정보 유출이다