Vercel 로그 조회와 전송: Runtime Logs, CLI, Log Drains
Vercel Runtime Logs와 CLI로 실패한 요청을 찾고, Log Drains의 JSON·NDJSON 전송과 수신 서명 검증을 설정하는 방법을 살펴봅니다.
배포 직후 운영 환경에서 500 응답이 나왔다면 프로젝트의 Logs 화면부터 엽니다. 문제가 난 요청을 어떤 배포 버전이 처리했는지 찾습니다. 배포 자체가 끝나지 않았다면 배포 상세 화면의 Build Logs를 봅니다. 요청이 함수까지 도달했는지부터 확인하면 조사 범위가 좁아집니다.
Runtime Logs에서 실패한 요청 찾기
환경과 시간 범위를 먼저 좁힌 뒤 배포를 지정합니다. 요청 ID가 있으면 함께 검색합니다. Vercel Functions와 Routing Middleware의 실행 로그는 Logs에서 볼 수 있습니다. 방화벽이 요청을 차단한 것으로 보이면 Firewall 화면도 확인합니다. 캐시에서 응답했다면 해당 요청에 새 함수 로그가 남지 않을 수 있습니다. Runtime Logs · Firewall 관측
아래 명령은 연결된 프로젝트에서 지정한 운영 배포의 런타임 오류를 조회합니다. dpl_example을 실제 배포 ID로 바꿉니다.
vercel logs runtime --deployment dpl_example --environment production \
--since 30m --query 'level:error' --limit 50
Vercel CLI v64 이상에서 쓰는 문법입니다. level:error는 로그 레벨을 거르는 조건입니다. HTTP 500 응답을 찾으려면 vercel logs requests의 CDN 요청 기록을 httpStatus로 조회합니다. --json을 붙이면 각 로그의 본문은 .data에 들어가고, 마지막 줄에 별도의 요약 레코드가 붙습니다. Vercel CLI 로그 명령
2026년 11월 10일 기준 공식 문서에 따르면 Runtime Logs는 Hobby 1시간, Pro 1일, Enterprise 3일 동안 보관됩니다. 적용 대상 프로젝트에 Observability Plus를 사용하면 30일 동안 보관되며, 한 번에 조회할 수 있는 범위는 연속 14일까지입니다. 보관 기간이 지난 로그는 조회 범위를 넓혀도 돌아오지 않습니다. Observability Plus
함수 로그에 검색할 필드 남기기
“결제 실패”라는 문장만 남기면 다음 장애에서도 메시지 전체를 훑어야 합니다. event와 outcome처럼 배포 버전이 바뀌어도 의미가 유지되는 필드를 둡니다. 아래는 Next.js App Router에서 쓰는 점검용 Route Handler입니다. 고객 데이터를 읽지 않고 JSON 한 줄만 출력합니다. Next.js Route Handlers
export async function POST() {
console.log(JSON.stringify({
event: "checkout_probe",
outcome: "ok",
}));
return Response.json({ ok: true });
}
이 한 줄은 드레인 레코드의 message에 문자열로 들어올 수 있습니다. 수신 측에서 파싱하고, Vercel의 level이나 응답 상태 코드와는 별도 필드로 저장합니다. 예를 들어 console.error 출력은 error 레벨로 기록됩니다. 토큰, 개인정보, 원본 요청 본문은 로그에 남기지 않습니다. Log Drain 레코드 구조
Log Drain 전송 범위 정하기
Log Drains는 Pro와 Enterprise에서 쓸 수 있으며 Pro Trial은 제외됩니다. 팀 설정 권한이 있는 계정으로 Team Settings → Drains를 열고 Log와 Custom Endpoint를 고릅니다. 먼저 필요한 프로젝트, 환경, 로그 소스만 선택합니다. 형식은 배치 단위 JSON 배열 또는 한 줄에 객체 하나가 오는 NDJSON 중에서 고릅니다. 샘플링 규칙이 없으면 선택 범위의 로그가 전송됩니다. 규칙을 설정했다면 첫 번째로 일치하는 규칙이 적용되고, 일치하는 규칙이 없는 요청은 전송되지 않습니다. Vercel Drains · Drain 설정
Vercel은 HTTPS POST로 전송합니다. 수신 측에서 본문을 파싱하거나 변환하기 전에 원본 바이트와 x-vercel-signature로 서명을 검증합니다. 다음 Node.js 함수에는 본문 Buffer와 헤더 값을 전달합니다. 비밀 키는 서버 설정에서 읽어 옵니다.
import { createHmac, timingSafeEqual } from "node:crypto";
export function validDrainSignature(rawBody, signature, secret) {
if (!Buffer.isBuffer(rawBody) ||
typeof signature !== "string" || !/^[0-9a-f]{40}$/i.test(signature) ||
typeof secret !== "string" || !secret.length) {
return false;
}
const expected = createHmac("sha1", secret).update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}
요청 크기에 상한을 둡니다. 서명을 검증한 다음 형식이 깨진 배치나 JSON 객체가 아닌 항목은 거부합니다. 배치가 유실되지 않도록 저장한 뒤 HTTP 200을 반환합니다. Custom Headers를 추가 인증에 사용할 수도 있습니다. 관리 화면에서 전송 실패를 확인할 수 있지만, 현재 공식 문서는 고정 재시도 일정이나 과거 로그 재전송을 보장하지 않습니다. 수신 누락을 살피고 프로젝트 ID와 레코드 ID로 중복 저장을 방지합니다. Drain 수신 보안 · 전송 오류 확인
수신한 로그에서 확인할 항목
드레인의 Test를 실행한 뒤 선택한 환경에서 새 로그를 한 건 만들고, 수신 측에서 배포 ID로 찾습니다. timestamp가 유닉스 에포크 기준 밀리초로 해석되는지 확인합니다. 선택 필드인 숫자 statusCode와 로그 level도 각각 검색할 수 있어야 합니다. 빌드 로그에는 requestId가 없을 수 있습니다. 최상위 statusCode의 -1은 Lambda가 비정상 종료되어 응답을 내지 못했음을 뜻합니다. proxy.statusCode의 -1은 ISR 백그라운드 재검증을 뜻합니다. 두 값 모두 실제 HTTP 상태 코드와 구분합니다. Log Drain 레코드 구조
Guance에서는 DataKit의 Log Streaming 수집기가 /v1/write/logstreaming을 제공합니다. 연결하기 전에 입력 형식과 인증 요구 사항을 확인합니다. 형식 변환이 필요하면 HTTPS 수신기에서 서명을 검증한 후 이벤트를 정리해 DataKit으로 전달합니다. 로그 탐색기에서 배포 ID를 지정하면 같은 버전의 오류와 응답 상태를 함께 살펴볼 수 있습니다. Guance Log Streaming · Guance 로그 탐색기
