Lambda 타임아웃 늘리기: 설정 위치, 최대 한도, 실전 주의사항

Lambda 함수가 3초 만에 끊기는데 실제 작업은 10초가 필요한 상황 — 처음 마주치면 당황스럽지만, 원인은 단순하다. Lambda의 기본 타임아웃이 3초로 설정되어 있고, 이 값을 명시적으로 늘리지 않으면 함수는 작업 완료 여부와 무관하게 강제 종료된다. 이 글에서는 Lambda 타임아웃 설정 위치, 최대 한도, 그리고 단순히 값을 올리는 것 이상으로 놓치기 쉬운 실전 주의사항을 정리한다.

TL;DR — Lambda 타임아웃 핵심 요약

항목	내용
기본 타임아웃	3초
최대 타임아웃	900초 (15분)
설정 단위	함수 단위 (버전/별칭별 독립 설정 불가)
타임아웃 측정 범위	전체 호출 시간 — 콜드 스타트 init 단계 포함
설정 방법	콘솔, AWS CLI, IaC (SAM/CDK/Terraform)
연동 서비스 타임아웃	API Gateway(29초), ALB(60초) 등 별도 제한 존재

Lambda 타임아웃이 동작하는 방식

Lambda 타임아웃은 함수 호출이 시작된 시점부터 카운트된다. 중요한 점은 타임아웃이 핸들러 실행 시간만이 아닌 전체 호출 시간에 적용된다는 것이다. 콜드 스타트가 발생하면 런타임 초기화(init) 단계도 이 시간에 포함된다. 즉, init에 2초가 걸리고 핸들러 로직에 9초가 필요한 함수라면, 타임아웃을 10초로 설정해도 강제 종료될 수 있다.

타임아웃이 초과되면 Lambda는 Task timed out after X.XX seconds 메시지와 함께 호출을 종료하고, 호출자에게 오류를 반환한다. 함수 내부에서 try/catch로 잡을 수 없다 — 런타임 레벨에서 강제 중단되기 때문이다.

graph TD A["Lambda 호출 시작
타임아웃 카운터 시작"] --> B{"콜드 스타트?"}; B -- "Yes" --> C["Init 단계
런타임 초기화 / 코드 로딩"]; C --> D["핸들러 실행"]; B -- "No (Warm)" --> D; D --> E{"타임아웃 초과?"}; E -- "No" --> F["정상 응답 반환"]; E -- "Yes" --> G["강제 종료
Task timed out 오류"];

1. 호출 시작: Lambda 서비스가 호출을 수신하고 타임아웃 카운터를 시작한다.
2. Init 단계 (콜드 스타트 시): 런타임 초기화, 코드 로딩, 핸들러 외부 코드 실행. 이 시간도 타임아웃에 포함된다.
3. 핸들러 실행: 실제 비즈니스 로직이 실행된다.
4. 정상 완료 또는 강제 종료: 설정된 타임아웃 내에 완료되면 응답 반환, 초과하면 오류 반환.

Lambda 타임아웃 설정 방법

방법 1: AWS 콘솔에서 변경

가장 빠른 방법이다. Lambda 콘솔 → 함수 선택 → 구성(Configuration) 탭 → 일반 구성(General configuration) → 편집(Edit) → 타임아웃 값 수정 → 저장.

슬라이더 또는 분/초 입력 필드로 설정할 수 있다. 최대값은 15분(900초)이다.

방법 2: AWS CLI로 변경

배포 자동화나 스크립트 기반 운영 환경에서 사용한다. update-function-configuration 명령으로 타임아웃을 변경한다.

aws lambda update-function-configuration \
  --function-name my-function \
  --timeout 30

변경 후 현재 설정을 확인하려면:

aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Timeout'

방법 3: AWS SAM 템플릿

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Timeout: 30

방법 4: AWS CDK (TypeScript)

import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Duration } from 'aws-cdk-lib';

const myFunction = new lambda.Function(this, 'MyFunction', {
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('lambda'),
  timeout: Duration.seconds(30),
});

Lambda 타임아웃 설정 시 놓치기 쉬운 함정들

함정 1: API Gateway의 독립적인 타임아웃 제한

Lambda 타임아웃을 60초로 늘렸는데도 29초에 오류가 발생한다면, 문제는 Lambda가 아니다. Amazon API Gateway(REST API)는 통합 타임아웃이 최대 29초로 고정되어 있다. Lambda 타임아웃이 아무리 길어도 API Gateway가 먼저 연결을 끊는다.

API Gateway를 프론트엔드로 사용하는 구조에서 Lambda 타임아웃만 늘리는 것은, 수도관을 굵게 교체했는데 밸브가 그대로인 것과 같다. 병목은 Lambda 바깥에 있다.

이 경우 아키텍처를 재검토해야 한다. 비동기 패턴(SQS + Lambda, Step Functions)으로 전환하거나, API Gateway 대신 ALB(최대 4,000초 유휴 타임아웃)를 사용하는 방법을 고려한다.

API Gateway 통합 타임아웃 현재 설정 확인:

aws apigateway get-integration \
  --rest-api-id YOUR_API_ID \
  --resource-id YOUR_RESOURCE_ID \
  --http-method POST \
  --query 'timeoutInMillis'

함정 2: VPC 연결 함수의 콜드 스타트와 타임아웃

Lambda 함수를 VPC에 연결하면 Elastic Network Interface(ENI) 프로비저닝이 초기화 과정에 포함될 수 있다. 앞서 설명했듯 타임아웃은 전체 호출 시간에 적용되며, 콜드 스타트 시 발생하는 init 단계도 포함된다. VPC 연결 함수에서 콜드 스타트가 길어지면 핸들러 로직 실행 전에 타임아웃이 소진될 수 있다. VPC Lambda의 타임아웃을 설정할 때는 예상 init 시간을 반드시 포함해서 계산해야 한다.

현재 함수의 실제 초기화 시간은 CloudWatch Logs Insights로 확인할 수 있다:

fields @timestamp, @message
| filter @message like /Init Duration/
| stats avg(@initDuration), max(@initDuration) by bin(5m)

함정 3: 타임아웃과 비용의 관계

Lambda 요금은 요청 수와 실행 시간(GB-초 단위)을 기준으로 청구된다. 타임아웃을 필요 이상으로 높게 설정하면, 함수가 무한 루프나 교착 상태에 빠졌을 때 최대 타임아웃까지 비용이 발생한다. 실제 실행 시간의 2~3배 정도를 상한선으로 설정하는 것이 실용적이다. 정확한 요금은 AWS Lambda 요금 페이지에서 확인한다.

실전 경험: 타임아웃 오류인데 타임아웃이 아니었던 케이스

Lambda 타임아웃 관련 트러블슈팅에서 자주 마주치는 패턴이 있다. 함수가 5초 타임아웃으로 설정되어 있고, CloudWatch Logs에 Task timed out after 5.00 seconds가 찍힌다. 당연히 타임아웃을 30초로 늘린다. 그런데 이번엔 30초에 똑같은 메시지가 뜬다.

실제 원인은 외부 HTTP 엔드포인트 호출에서 응답 대기 중 블로킹이 발생한 것이었다. 타임아웃을 늘릴수록 그만큼 더 기다리다 죽는 구조였다. 올바른 진단은 타임아웃 값이 아니라 어느 코드 라인에서 시간이 소비되는지를 먼저 파악하는 것이다.

AWS X-Ray를 활성화하면 함수 내 세그먼트별 실행 시간을 추적할 수 있다:

aws lambda update-function-configuration \
  --function-name my-function \
  --tracing-config Mode=Active

X-Ray 추적 결과에서 어느 서브세그먼트가 대부분의 시간을 차지하는지 확인한 뒤, 타임아웃 조정 여부를 결정하는 것이 순서다.

graph LR A["CloudWatch Logs
Task timed out 확인"] --> B["X-Ray 추적 활성화"]; B --> C["세그먼트별 시간 분석"]; C --> D{"병목 원인"}; D -- "로직 자체가 느림" --> E["타임아웃 값 증가"]; D -- "외부 호출 블로킹" --> F["코드 수정
(타임아웃 설정, 비동기 처리)"]; D -- "Init 시간 과다" --> G["Provisioned Concurrency
또는 아키텍처 재검토"];

1. 로그 확인: CloudWatch Logs에서 'Task timed out' 메시지와 실제 소요 시간 확인.
2. X-Ray 추적: 어느 세그먼트에서 시간이 소비되는지 파악. 외부 호출, DB 쿼리, 초기화 코드 등을 구분.
3. 원인 분류: 로직 자체가 느린지(타임아웃 증가 필요) vs. 블로킹/무한 대기인지(코드 수정 필요) 판단.
4. 타임아웃 조정: 실제 실행 시간 기반으로 적절한 상한선 설정.

IAM 권한 — 타임아웃 변경에 필요한 최소 권한

타임아웃 설정 변경은 lambda:UpdateFunctionConfiguration 권한이 필요하다. 읽기 전용으로 현재 설정만 확인하려면 lambda:GetFunctionConfiguration으로 충분하다.

🔽 최소 권한 IAM 정책 예시 (클릭하여 펼치기)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunctionConfiguration"
      ],
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:my-function"
    }
  ]
}

Lambda 타임아웃 설정 마무리 및 다음 단계

Lambda 타임아웃 변경 자체는 단순하다. 콘솔이나 CLI에서 값을 수정하면 즉시 반영된다. 실제 운영에서 중요한 것은 세 가지다: 타임아웃이 전체 호출 시간(init 포함)을 기준으로 측정된다는 점, API Gateway 같은 연동 서비스의 독립적인 타임아웃 제한을 함께 확인해야 한다는 점, 그리고 타임아웃을 늘리기 전에 X-Ray로 실제 병목을 먼저 파악해야 한다는 점이다.

15분이 넘는 작업이 필요하다면 Lambda는 적합한 선택이 아니다. AWS Step Functions, ECS Fargate, 또는 AWS Batch를 검토하라.

• AWS Lambda 함수 구성 공식 문서
• AWS X-Ray와 Lambda 통합 문서

용어 정리

용어	설명
타임아웃 (Timeout)	Lambda 함수 호출에 허용된 최대 실행 시간. 전체 호출 시간에 적용되며, 콜드 스타트 시 발생하는 초기화(init) 단계도 포함된다. 초과 시 함수는 강제 종료된다.
콜드 스타트 (Cold Start)	함수 인스턴스가 새로 생성될 때 발생하는 초기화 지연. init 단계가 타임아웃 시간을 소비한다.
Init 단계	콜드 스타트 시 런타임 초기화, 코드 로딩, 핸들러 외부 코드 실행이 이루어지는 단계. 타임아웃 측정에 포함된다.
통합 타임아웃 (Integration Timeout)	API Gateway가 백엔드(Lambda 등) 응답을 기다리는 최대 시간. REST API 기준 최대 29초.
X-Ray 추적	Lambda 함수 내 세그먼트별 실행 시간을 시각화하는 AWS 분산 추적 서비스. 타임아웃 원인 분석에 활용한다.

Related Posts

• 📄 Lambda 환경 변수 완전 가이드: DB 엔드포인트 주입부터 KMS 암호화까지
• 📄 Lambda S3 무한 루프 완전 차단 가이드 — 재귀 트리거 방지 실전