[Vercel][운영] FUNCTION_INVOCATION_TIMEOUT 뒤 Runtime Logs에서 외부 API 대기와 메모리 압박을 나누는 법

IT 리서치 노트

[Vercel][운영] FUNCTION_INVOCATION_TIMEOUT 뒤 Runtime Logs에서 외부 API 대기와 메모리 압박을 나누는 법

Vercel에서 `FUNCTION_INVOCATION_TIMEOUT`이 나면 많은 팀이 먼저 `maxDuration`을 올린다. 하지만 2026년 6월 27일 기준 Vercel 공식 문서를 다시 보면, timeout 원인은 느린 네트워크 호출, 함수 내부 문제, 실행 환경 이슈까지 넓다. 이 글은 Runtime Logs와 메모리 확인 경로를 기준으로 외부 API 대기와 함수 내부 메모리 압박을 어떻게 나눠 읽을지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 FUNCTION_INVOCATION_TIMEOUT 뒤에는 먼저 Runtime Logs로 외부 API 대기 신호가 있는지 보고, 그다음 함수 memory size와 최근 리소스 변경을 같이 확인해야 한다. 외부 의존성이 느린 경우에는 duration을 늘려도 비용만 커질 수 있고, 반대로 메모리 압박이면 upstream만 의심하다가 시간을 버릴 수 있다. 그래서 timeout 후 첫 분기점은 maxDuration이 아니라 로그 패턴과 함수 리소스 확인이다.

이미 FUNCTION_INVOCATION_TIMEOUT 기본 글이 duration과 runtime logs 출발점을 설명했다면, 이번 글은 그 안에서 외부 API 대기와 메모리 압박을 나누는 후속 단계다. health check 비용 글처럼 원인보다 비용이 먼저 새는 구조와도 감각이 닿아 있다.

그리고 Runtime Logs에 실제로 memory 경고가 찍힌 상태라면 판단을 한 단계 더 좁혀야 한다. 어느 화면에서 현재 function memory size를 확인하고 Logs, Observability, 함수 설정을 어떤 순서로 맞춰 볼지는 memory 경고 후속 글에서 따로 정리했다. 이 글이 timeout 원인의 큰 분기라면, 후속 글은 memory 신호가 이미 보인 상황에서 다음 확인 지점을 빠르게 줄이는 데 가깝다.

2. 어디서 실제로 막히는가

현장에서 자주 보는 오해는 세 가지다. 첫째, 504 timeout을 곧바로 함수 코드가 느리다고 단정한다. 둘째, 외부 API가 느린데 maxDuration만 키운다. 셋째, memory size가 낮아 재시작 또는 처리 지연이 생기는데 upstream timeout과 같은 증상으로 뭉뚱그린다.

Vercel의 timeout 에러 문서는 느린 네트워크 호출과 환경 이슈를 원인으로 분명히 적고 있다. debug slow functions 문서는 외부 API latency를 먼저 확인하라고 말한다. memory 문서는 Observability에서 함수별 메모리 크기를 확인하는 경로를 제공한다. duration 문서는 코드가 실행될 때만 Active CPU가 과금되고 I/O 대기 중에는 멈춘다고 설명한다.

이 네 문서를 합치면 실무 해석이 생긴다. 로그에 upstream timeout이나 connection refused가 반복되면 외부 대기 가능성이 높다. 반대로 최근 배포에서 memory size를 올린 뒤 증상이 줄거나, 큰 payload 처리 직후만 timeout이 난다면 함수 내부 압박 가능성이 커진다. 이 분기는 문서 여러 개를 합쳐 만든 실무 추론이며, 그래서 한 문서만 보면 놓치기 쉽다.

• 증상: 같은 route에서 504 timeout이 반복된다.
• 실패: 로그를 보기 전에 maxDuration부터 올린다.
• 막힘: 외부 API 대기와 메모리 압박을 같은 timeout으로 취급한다.
• 누락: Runtime Logs와 함수 memory size 확인 경로를 연결하지 않는다.

증상	먼저 볼 곳	판단 기준
504와 upstream timeout이 같이 보인다	Runtime Logs	외부 API 대기 가능성이 높다
큰 요청에서만 반복된다	memory size와 배포 변경	함수 내부 압박 가능성을 본다
모든 요청이 늘 길다	duration 설계	작업 자체를 분리해야 하는지 본다

3. 실무에서 적용하는 순서

timeout 이후 점검 순서는 다섯 단계가 가장 실용적이다. 먼저 Runtime Logs에서 504가 난 route와 RequestId를 모은다. 다음으로 upstream timeout, refused, DNS, TLS 같은 외부 대기 신호를 찾는다. 세 번째로 같은 함수의 memory size와 최근 배포 시점 변경을 확인한다. 네 번째로 duration을 키우기 전에 외부 의존성 timeout, cache, retry 정책을 점검한다. 마지막으로 작업 자체가 길다면 streaming이나 background 처리로 구조를 나눈다.

1. Runtime Logs에서 같은 route의 504 묶음을 먼저 모은다.
2. 외부 API 대기 신호가 있는지 query와 메시지로 찾는다.
3. 함수 memory size와 최근 리소스 변경을 같이 본다.
4. 원인을 나눈 뒤에만 maxDuration 또는 memory size를 조정한다.
5. 길게 살아야 하는 작업은 streaming 또는 background로 분리한다.

점검 메모 예시

path=/api/policy-sync
status=504
runtime_log_query=timeout OR ECONNREFUSED OR upstream
memory_size_checked=true
recent_memory_change=false
next_action=upstream timeout or cache review

여기서 중요한 점은 duration 조정이 마지막은 아니어도 두 번째 단계는 아니라는 것이다. 외부 대기 원인이면 upstream과 cache 설계가 먼저고, 내부 압박이면 함수 memory size와 payload 구조가 먼저다. duration은 그 두 가지가 정리된 뒤에야 근거 있게 올릴 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 Vercel의 timeout 에러 문서다. 여기서는 이 에러가 단순히 maxDuration 값 하나의 문제가 아니라 함수 내부 오류, 느린 네트워크 호출, 실행 환경 이슈에서 올 수 있다고 명시한다.

Vercel은 `FUNCTION_INVOCATION_TIMEOUT` 원인을 함수 내부 오류, 느린 네트워크 호출, 환경 이슈까지 넓게 잡아 설명한다.

즉 timeout이 났다고 곧바로 `maxDuration`만 올리는 것은 성급하다. 먼저 로그에서 외부 대기와 함수 자체 압박을 나눠야 같은 비용을 반복해서 늘리지 않는다.

두 번째 자료는 Runtime Logs 문서다. 여기서는 로그 탭에서 execution, status, path, RequestId 같은 기본 항목을 볼 수 있다고 설명한다.

Runtime Logs는 request별 실행 정보와 상태 코드를 같이 볼 수 있는 기본 출발점이다.

timeout 분기 작업은 이 화면에서 시작하는 편이 가장 빠르다. 동일한 경로의 504 묶음을 먼저 모아야 외부 API 대기인지 메모리 압박인지 패턴이 보인다.

세 번째 자료는 느린 함수 디버깅 가이드의 external API latency 구간이다. Vercel은 느린 함수가 실제로는 외부 API 대기 때문에 생기는 경우가 많다고 설명한다.

Vercel은 느린 함수 원인 중 하나로 외부 API latency를 먼저 확인하라고 안내한다.

이 문구는 timeout 이후 첫 분기점을 만든다. Runtime Logs에 upstream timeout, refused, DNS, TLS 같은 신호가 같이 보이면 함수 코드보다 외부 의존성 대기를 먼저 의심하는 편이 맞다.

네 번째 화면은 함수 메모리 크기 확인 경로다. 문서는 Observability에서 함수별 메모리 크기를 확인할 수 있다고 설명한다.

Vercel은 Observability에서 함수별 memory size를 확인하는 경로를 제공한다.

공식 문서가 timeout과 memory pressure를 한 문단으로 묶어 주지는 않는다. 하지만 timeout 분석에서 메모리 크기와 최근 배포 리소스 변경을 같이 봐야 하는 이유는 여기서 나온다. 외부 대기와 달리 메모리 압박은 리소스 설정과 배포 후 행동 변화를 같이 남긴다.

다섯 번째 자료는 duration 문서의 billing 설명이다. 여기서는 코드가 실행될 때만 Active CPU가 과금되고, I/O를 기다릴 때는 멈춘다고 적혀 있다.

duration 문서는 I/O 대기와 실제 코드 실행을 같은 비용 축으로 보지 말라고 사실상 알려 준다.

이 설명을 Runtime Logs와 합치면 운영 판단이 쉬워진다. 대기 시간이 긴데 CPU 실행 신호가 약하면 외부 의존성 쪽, 반대로 응답 전 구간이 모두 바쁘고 메모리 상향으로 완화되면 함수 내부 압박 쪽일 가능성이 높다. 이 해석은 공식 문서들을 합쳐 만든 실무 추론이다.

실무에서는 로그 패턴 비교가 있어야 분기가 빨라진다. upstream timeout, connection refused, memory size 조정 전후 배포 메모를 한 묶음으로 보면 어느 쪽을 먼저 볼지 결정하기 쉽다.

timeout 뒤 로그에서 외부 API 대기와 메모리 압박을 나누는 예시다.

이미 FUNCTION_INVOCATION_TIMEOUT 기본 글을 읽었다면, 이번 예시는 그다음 단계인 원인 분기표다.

마지막 자료는 분기 기준을 표로 고정한 것이다. 로그 신호, 리소스 확인 위치, 다음 조치가 한 표에 있으면 팀 내 인수인계도 쉬워진다.

외부 API 대기와 메모리 압박을 나누는 점검표다.

이 표는 timeout이 난 뒤 바로 조치하기 위한 운영 메모로 쓰기 좋다. 비용 판단까지 보려면 duration과 memory 글도 이어서 보면 흐름이 맞는다.

5. 주의사항과 리스크

첫 번째 리스크는 외부 API latency를 무시하고 duration만 늘려 504 빈도는 줄여도 비용과 사용자 대기 시간을 같이 키우는 것이다. 두 번째 리스크는 memory size 상향이 일시적으로 증상을 숨겼다고 해서 내부 로직 적재량 문제를 방치하는 것이다. 세 번째 리스크는 Runtime Logs 보관 기간을 몰라 필요한 시점의 로그를 놓치는 것이다.

공식 문서가 timeout과 memory pressure를 바로 대조표로 주지는 않는다. 따라서 이 글의 분기표는 Vercel 공식 문서 여러 개를 합쳐 만든 운영 해석이다. 실제 서비스에서는 route 특성과 upstream 구성에 따라 예외가 있을 수 있으므로, 한 번의 memory 상향이나 한 번의 retry 성공만으로 원인을 확정하지 않는 편이 좋다.

• duration 증설은 원인 분리 뒤에 한다.
• memory size 조정 전후 배포 메모를 남긴다.
• Runtime Logs 보관 기간과 검색 쿼리를 팀 운영 문서에 적어 둔다.

6. 결론

FUNCTION_INVOCATION_TIMEOUT은 하나의 에러 코드지만 원인은 하나가 아니다. Runtime Logs의 upstream 신호와 함수 memory size 확인 경로를 함께 보면 외부 API 대기, 내부 메모리 압박, 단순 duration 부족을 더 빨리 나눌 수 있다. 이 분기를 먼저 해야 maxDuration과 memory size 조정도 덜 헛돈다.

• 504가 나면 먼저 Runtime Logs에서 외부 대기 신호를 찾는다.
• 동시에 함수 memory size와 최근 배포 변경을 확인한다.
• 원인을 나눈 뒤에만 duration이나 memory를 조정한다.

7. 참고 링크

1. https://vercel.com/docs/errors/function_invocation_timeout
2. https://vercel.com/docs/logs/runtime
3. https://vercel.com/docs/functions/debug-slow-functions
4. https://vercel.com/docs/functions/configuring-functions/memory
5. https://vercel.com/docs/functions/configuring-functions/duration