왜 Vercel CLI에서 바로 웹 바이탈을 조회해야 할까?
웹 성능 최적화는 이제 선택이 아닌 필수입니다. 특히 Core Web Vitals(LCP, INP, CLS)는 SEO와 사용자 경험에 직접적인 영향을 미치죠. 하지만 매번 대시보드에 접속해서 데이터를 확인하는 건 번거롭습니다. 더군다나 장애 대응이나 배포 후 회귀(regression) 분석을 할 때는 즉각적인 데이터가 필요합니다.
Vercel이 공개한 새로운 CLI 명령어 vercel metrics는 이러한 니즈를 정확히 해결합니다. 터미널에서 바로 Speed Insights 데이터를 쿼리할 수 있어, 개발 워크플로우 안에서 성능 데이터를 확인하고 분석할 수 있습니다. 특히 AI 코딩 에이전트와 연동하면 더욱 강력해집니다. 에이전트에게 "지난주 대비 INP가 나빠진 페이지를 알려줘"라고 물어보면, CLI를 통해 데이터를 가져와 바로 답변해줍니다.
이 글에서는 vercel metrics 명령어의 기본 사용법부터, 실제 운영 환경에서 활용할 수 있는 고급 쿼리 패턴까지 상세히 다룹니다.
근거 자료: Vercel 공식 변경 로그
vercel metrics 명령어 기본 사용법
가장 먼저, Vercel CLI가 최신 버전인지 확인하고 명령어를 실행합니다.
# Vercel CLI 최신 버전 확인 및 업데이트
npm i -g vercel@latest
# 특정 프로젝트의 Speed Insights 데이터 조회
vercel metrics --project=my-project-name
# 특정 기간의 데이터만 보고 싶다면?
vercel metrics --project=my-project-name --from=2024-01-01 --to=2024-01-31
기본 출력은 모든 페이지의 평균 LCP, INP, CLS, FCP, TTFB 값을 보여줍니다. 하지만 더 세밀한 분석을 위해 **필터(dimensions)**와 쿼리 옵션을 사용할 수 있습니다.
주요 쿼리 예제
# 1. 특정 페이지의 지난주 대비 INP 회귀 확인
vercel metrics --project=my-project \
--path=/dashboard \
--metric=INP \
--from=$(date -d '7 days ago' +%Y-%m-%d) \
--to=$(date +%Y-%m-%d)
# 2. 아시아 지역의 홈페이지 속도 확인
vercel metrics --project=my-project \
--path=/ \
--dimension=country \
--filter=country:KR,JP,CN
# 3. 모바일 vs 데스크탑 CLS 비교
vercel metrics --project=my-project \
--metric=CLS \
--dimension=device \
--filter=device:mobile,desktop
팁: --filter 옵션은 key:value 형태로 여러 개를 조합할 수 있습니다. 지원하는 dimension 목록은 공식 문서에서 확인하세요.
AI 코딩 에이전트와 연동하기
이 기능의 진가는 AI 에이전트(예: Claude, GPT-4 등)와 결합할 때 발휘됩니다. 에이전트가 터미널 명령어를 실행할 수 있다면, 다음과 같은 대화가 가능합니다.
# 에이전트에게 질문: "지난주 대비 INP가 10% 이상 증가한 페이지를 알려줘"
# 에이전트가 내부적으로 실행할 명령어:
vercel metrics --project=my-project \
--metric=INP \
--from=2024-10-01 \
--to=2024-10-08 \
--format=json \
--order=asc
에이전트는 JSON 출력을 파싱하여 특정 임계값을 초과하는 페이지를 찾아내고, 원인 분석을 위한 추가 조치(예: 해당 페이지의 Lighthouse 리포트 요청)를 제안할 수 있습니다. 이는 **대화형 옵저버빌리티(Conversational Observability)**의 시작입니다.
고급 활용: 배포 파이프라인에 성능 게이트 추가하기
CI/CD 파이프라인에서 vercel metrics를 활용하면 성능 회귀를 자동으로 감지할 수 있습니다. 예를 들어, 배포 전에 현재 프로덕션 데이터와 프리뷰 데이터를 비교하는 스크립트를 작성할 수 있습니다.
#!/bin/bash
# 배포 전 성능 체크 스크립트
# 현재 프로덕션의 평균 LCP 가져오기
PROD_LCP=$(vercel metrics --project=my-project \
--metric=LCP \
--from=$(date -d '1 day ago' +%Y-%m-%d) \
--to=$(date +%Y-%m-%d) \
--format=json | jq '.data[0].value')
# 프리뷰 배포의 LCP 가져오기 (프리뷰 URL 필요)
PREVIEW_LCP=$(vercel metrics --project=my-project \
--url=https://preview-url.vercel.app \
--metric=LCP \
--format=json | jq '.data[0].value')
# 임계값 비교 (10% 이상 증가하면 실패)
THRESHOLD=$(echo "$PROD_LCP * 1.1" | bc)
if (( $(echo "$PREVIEW_LCP > $THRESHOLD" | bc -l) )); then
echo "❌ LCP가 프로덕션 대비 10% 이상 증가했습니다. 배포를 중단합니다."
exit 1
else
echo "✅ LCP 정상 범위 내입니다."
fi
이 스크립트를 GitHub Actions, GitLab CI, Jenkins 등에 통합하면, 성능이 나빠지는 배포를 사전에 차단할 수 있습니다.
주의사항 및 한계
- 데이터 지연: Speed Insights는 실제 사용자 데이터를 기반으로 하므로, 트래픽이 적은 페이지는 데이터가 없거나 지연될 수 있습니다.
- 필터의 정확성:
country나device같은 dimension은 브라우저에서 수집된 정보에 의존하므로, 일부 데이터가 누락될 수 있습니다. - 비용: Vercel Pro 플랜 이상에서만 Speed Insights 기능을 사용할 수 있습니다. Hobby 플랜에서는 사용이 제한됩니다.
한국 개발 생태계에서의 적용 맥락
국내에서도 Vercel을 사용하는 스타트업과 프리랜서 개발자들이 늘고 있습니다. 특히 Next.js 기반 프로젝트에서 Vercel의 Speed Insights는 네이버, 카카오 등 국내 검색 엔진의 Core Web Vitals 반영 수준을 모니터링하는 데 매우 유용합니다. CLI 기반 접근은 SI 프로젝트처럼 여러 도메인을 관리해야 하는 환경에서 특히 빛을 발합니다. 각 프로젝트마다 대시보드에 로그인할 필요 없이, 하나의 터미널에서 모든 사이트의 성능을 한눈에 확인할 수 있으니까요.
결론: CLI가 여는 대화형 옵저버빌리티의 미래
vercel metrics 명령어는 단순한 편의 기능을 넘어, 개발자 경험(DX)을 근본적으로 변화시키는 도구입니다. 대시보드에 의존하던 성능 모니터링을 개발 워크플로우 안으로 가져옴으로써, 더 빠르고 정확한 의사 결정을 내릴 수 있습니다.
특히 AI 에이전트와의 시너지는 앞으로 더욱 중요해질 것입니다. "배포 전에 성능 체크해줘"라는 명령 하나로 전체 파이프라인이 자동화되는 날이 머지않았습니다.
다음 단계 학습 방향:
- Vercel Speed Insights의 공식 문서를 탐독하며 지원하는 모든 dimension과 metric을 숙지하세요.
- GitHub Actions와 연동하여 실제 CI/CD 파이프라인에 성능 게이트를 구축해보세요.
- AI 에이전트(Claude, GPT-4 등)와 Vercel CLI를 연동하는 방법을 연구해보세요.
함께 보면 좋은 글