AWS Lambda 디버깅: 일반적인 호출 오류 및 해결 방법

AWS Lambda 호출 오류는 일반적으로 호출자가 함수를 호출할 수 없음, Lambda가 런타임을 시작할 수 없음, 또는 코드가 시작된 후 실패하는 세 가지 중 하나에서 발생합니다. 가장 빠른 해결 방법은 메모리, 시간 제한, IAM 정책 또는 VPC 설정을 변경하기 전에 어떤 단계에서 실패했는지 식별하는 것입니다.

CloudWatch Logs로 시작한 다음, 권한, 핸들러 설정, 종속성 및 네트워킹을 순서대로 확인하세요.

디버깅 기준 설정: CloudWatch Logs

함수를 변경하기 전에 로그 그룹 /aws/lambda/YourFunctionName을 확인하세요. 일반적인 Lambda 실행에는 일반적으로 다음과 같은 플랫폼 로그 라인이 포함됩니다.

1. START: 실행 시작을 나타냅니다.
2. END: 실행 완료를 나타냅니다.
3. REPORT: 요약 메트릭(기간, 청구 기간, 사용된 메모리, 최대 사용 메모리 및 X-Ray 추적 세부 정보)을 제공합니다.

함수가 시작되지 않으면 애플리케이션 로그가 표시되지 않을 수 있습니다. 이 경우 호출 서비스, Lambda 콘솔 테스트 결과, CloudTrail 이벤트 및 함수의 리소스 기반 정책을 확인하세요.

권한 및 액세스 오류 해결

권한 오류는 Lambda 호출 실패의 가장 일반적인 원인입니다. 일반적으로 함수를 실행할 권한이 없거나 호출 엔터티에 함수를 호출할 권한이 없는 두 가지 범주로 나뉩니다.

실행 역할(IAM 역할) 실패

모든 Lambda 함수는 IAM 실행 역할을 가정해야 합니다. 이 역할이 잘못 구성되면 함수가 필요한 AWS 서비스와 상호 작용할 수 없습니다.

일반적인 누락 권한:

필요한 서비스 액세스	필요한 IAM 정책 작업
CloudWatch에 로깅	logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents
VPC 연결	ec2:CreateNetworkInterface, ec2:DeleteNetworkInterface, ec2:DescribeNetworkInterfaces
S3/DynamoDB 읽기	s3:GetObject, dynamodb:GetItem 등

해결 방법:

1. AWS 콘솔에서 Lambda 함수 구성으로 이동합니다.
2. "권한" 탭을 확인하고 연결된 IAM 역할 정책을 검토합니다.
3. 역할에 기본 AWS 관리형 정책 AWSLambdaBasicExecutionRole이 있거나 사용자 지정 정책에 필요한 CloudWatch 작업이 포함되어 있는지 확인합니다.
4. 특정 버킷 접두사에 대한 s3:GetObject와 같이 코드에 실제로 필요한 서비스 권한만 추가합니다.

리소스 기반 정책 오류(호출 권한)

Lambda가 다른 서비스(S3, API Gateway, SNS 또는 교차 계정 호출 등)에 의해 호출되는 경우 해당 서비스에는 함수를 호출할 수 있는 명시적 권한이 필요합니다.

증상: 서비스(예: S3)가 Lambda를 트리거하려고 시도하지만 CloudWatch 로그에 아무것도 나타나지 않고 서비스에서 오류를 보고합니다.

해결 방법: add-permission CLI 명령 또는 해당 콘솔 설정을 사용하여 호출 권한을 부여합니다. 예를 들어 S3 버킷이 함수를 호출하도록 허용하려면 다음을 수행합니다.

aws lambda add-permission \
    --function-name my-processing-function \
    --statement-id S3InvokePermission \
    --action lambda:InvokeFunction \
    --principal s3.amazonaws.com \
    --source-arn arn:aws:s3:::my-trigger-bucket

교차 계정 호출의 경우 양쪽을 확인하십시오. 호출자에게 lambda:InvokeFunction을 호출할 IAM 권한이 필요하고 Lambda 함수에는 해당 호출자를 허용하는 리소스 기반 정책이 필요합니다.

구성 및 리소스 제약 오류

이러한 오류는 정의된 런타임 환경 설정 및 함수에 부과된 리소스 제한과 관련됩니다.

함수 시간 초과 오류

함수 시간 초과는 일반적인 실패로, 실행이 허용된 최대 시간을 초과했음을 나타냅니다. Lambda는 실행을 강제로 종료하고 Task timed out 오류를 기록합니다.

진단:

1. CloudWatch 로그에서 REPORT 라인을 확인합니다. Duration과 구성된 시간 제한을 비교합니다.
2. 함수가 일찍 시간 초과되면(예: 30초 제한 중 5초 후) 병목 현상은 초기화 또는 연결(예: DNS 조회 대기)일 가능성이 높습니다.

해결 방법:

• 시간 제한 증가: 작업이 본질적으로 장기 실행되는 경우(예: 대규모 데이터 처리) 시간 제한을 늘립니다(최대 15분).
• 코드/종속성 최적화: 작업이 느린 경우 코드를 프로파일링하여 병목 현상을 식별합니다. 외부 호출에 코드 내에서 합리적인 시간 제한이 정의되어 있는지 확인합니다.
• 콜드 스타트 처리: 대규모 초기화 프로세스는 시간 초과에 기여할 수 있습니다. 콜드 스타트가 중요한 경우 Lambda 프로비저닝된 동시성을 사용합니다.

메모리 소진 오류

함수에 할당된 것보다 더 많은 RAM이 필요한 경우 충돌이 발생하고 런타임에 따라 OutOfMemoryError 또는 유사한 메시지가 기록됩니다.

진단: CloudWatch REPORT 라인에서 Max Memory Used 메트릭을 검토합니다. 이 값이 구성된 Memory Size에 지속적으로 가깝거나 같으면 메모리 누수 또는 리소스 부족이 있을 수 있습니다.

해결 방법: 메모리 할당을 늘리고 다시 테스트합니다. Lambda는 더 많은 메모리를 할당할수록 더 많은 CPU를 할당하므로 메모리가 높을수록 일부 비용을 상쇄할 만큼 지속 시간을 줄일 수 있습니다. 비용이 더 저렴할 것이라고 가정하지 말고 자체 함수를 측정하십시오.

AWS Lambda Power Tuning은 특정 워크로드에 대한 메모리 설정을 비교하는 데 도움이 될 수 있습니다.

핸들러 잘못된 구성 (Runtime.HandlerNotFound)

이는 Lambda가 함수 구성에 정의된 진입점을 찾을 수 없을 때 발생합니다.

증상: Error: Runtime.HandlerNotFound 또는 유사한 시작 실패.

해결 방법: 함수 설정의 핸들러 필드가 [파일_이름].[함수_이름] 구조와 일치하는지 확인합니다. 예를 들어 my_code.py에 정의되고 진입 함수가 lambda_handler인 Python 함수는 핸들러가 my_code.lambda_handler로 설정되어야 합니다.

Node.js의 경우 핸들러 이름은 index.js에서 내보낸 handler 함수에 대한 index.handler와 같이 모듈 및 내보낸 함수를 따릅니다.

네트워킹 및 VPC 연결 문제

Lambda 함수가 Virtual Private Cloud(VPC) 내에서 실행되도록 구성되면 프라이빗 리소스에 액세스할 수 있지만 기본적으로 공용 인터넷 액세스는 손실됩니다.

인터넷 액세스 누락

Lambda가 VPC에 있고 외부 서비스에 연결해야 하는 경우 NAT 게이트웨이 또는 다른 승인된 송신 경로를 통해 인터넷으로의 경로가 필요합니다. 함수를 퍼블릭 서브넷에 배치해도 공용 IP 주소가 제공되지는 않습니다.

증상: HTTP 연결 실패, 공용 엔드포인트에 액세스할 때 시간 초과.

해결 방법:

1. 함수가 Lambda 워크로드용으로 설계된 프라이빗 서브넷에 연결되어 있는지 확인합니다.
2. 이러한 프라이빗 서브넷에 아웃바운드 인터넷 트래픽(0.0.0.0/0)을 NAT 게이트웨이로 전달하는 경로 테이블 항목이 있는지 확인합니다.
3. Lambda가 AWS 서비스에만 비공개로 액세스해야 하는 경우 S3 및 DynamoDB용 게이트웨이 엔드포인트 또는 지원되는 서비스용 인터페이스 엔드포인트와 같은 VPC 엔드포인트를 고려하십시오.

보안 그룹 및 ACL 제한

함수가 성공적으로 시작될 수 있지만 보안 그룹, 대상 보안 그룹, 네트워크 ACL 또는 경로 테이블이 연결을 차단할 때 중단될 수 있습니다.

해결 방법: Lambda 보안 그룹에서 대상 포트로의 아웃바운드 트래픽을 허용하고 Lambda 보안 그룹에서 대상 보안 그룹으로의 인바운드 트래픽을 허용합니다. 예를 들어 PostgreSQL에 연결하는 Lambda 함수는 Lambda에서 아웃바운드 TCP 5432가 필요하고 데이터베이스 측에서 인바운드 TCP 5432가 필요합니다.

실행 역할에 VPC 액세스에 필요한 EC2 네트워크 인터페이스 권한이 없으면 Lambda는 함수를 실행하는 데 필요한 VPC 네트워킹을 준비하는 동안 실패할 수 있습니다.

배포 및 런타임 잘못된 구성

이러한 문제는 코드 번들이 구성된 방식 또는 선택한 런타임 환경과 관련됩니다.

종속성 및 패키지 오류

코드가 특정 런타임 환경에 대해 올바르게 번들링되거나 설치되지 않은 외부 라이브러리에 의존하는 경우 함수는 초기화 중에 실패합니다.

증상: module not found, cannot import name 또는 No such file or directory와 같은 런타임 예외(Python 또는 Node.js에서 특히 일반적).

해결 방법:

1. 로컬 환경과 Lambda 환경: Lambda 런타임과 일치하는 환경에서 종속성을 빌드해야 합니다(예: Python에서 종속성을 올바르게 배치하려면 pip install -t . 사용).
2. Lambda 레이어 사용: 더 크고 안정적인 종속성을 Lambda 레이어로 패키징하여 기본 배포 패키지의 크기를 줄이고 배포 속도를 향상시킵니다.
3. 경로 확인: 런타임 구성이 설치된 종속성의 위치를 올바르게 가리키는지 확인합니다.

배포 패키지 크기 및 형식

Lambda에는 배포 패키지 크기 제한이 있으며, 이러한 제한은 .zip 파일을 직접 업로드하는지, Amazon S3를 통해 업로드하는지, 레이어를 사용하는지 또는 컨테이너 이미지를 배포하는지에 따라 다릅니다. 대규모 함수를 재구성하기 전에 패키징 방법에 대한 현재 Lambda 할당량을 확인하십시오.

증상: 크기 오류로 인해 배포가 실패하거나 대규모 패키지가 콜드 스타트 속도를 저하시킵니다.

해결 방법:

• 정리: 불필요한 파일, 문서 및 개발 종속성을 제거합니다.
• 레이어: 정적 자산 또는 대규모 종속성을 Lambda 레이어로 이동합니다.
• 컨테이너 이미지: 매우 큰 애플리케이션의 경우 Amazon ECR에서 함수를 컨테이너 이미지로 배포하는 것을 고려하십시오.

이벤트 및 페이로드 문제

일부 호출 오류는 이벤트 자체에서 발생합니다.

• 잘못된 형식의 JSON: 콘솔 테스트 및 CLI 호출에는 유효한 JSON 페이로드가 필요합니다.
• 예기치 않은 이벤트 모양: S3 이벤트, API Gateway 이벤트 및 EventBridge 이벤트에는 동일한 필드가 없습니다.
• 비동기 재시도 동작: 비동기 호출은 실패 후 재시도할 수 있으며 구성된 경우 실패한 이벤트를 대상 또는 데드 레터 큐로 보낼 수 있습니다.

직접 CLI 테스트의 경우 응답 및 로그를 캡처합니다.

aws lambda invoke \
    --function-name my-function \
    --payload '{"ping": true}' \
    --cli-binary-format raw-in-base64-out \
    response.json

--cli-binary-format raw-in-base64-out 옵션은 명령줄에서 원시 JSON을 직접 전달할 때 AWS CLI v2에서 일반적으로 필요합니다.

문제 해결 단계 요약

호출 오류가 발생하면 다음 체계적인 접근 방식을 따르십시오.

1. CloudWatch를 먼저 확인: START 라인 이전에 Lambda 서비스에서 기록한 즉각적인 오류를 찾습니다.
2. IAM 역할 확인: 함수의 실행 역할에 모든 필요한 권한(로깅, VPC 및 서비스 액세스)이 있는지 확인합니다.
3. 구성 검토: 핸들러 이름, 메모리 설정 및 시간 제한 한도를 확인합니다.
4. VPC 설정 분석: VPC를 사용하는 경우 보안 그룹, 서브넷 매핑 및 경로 테이블(NAT 게이트웨이 액세스의 경우 특히 중요)을 확인합니다.
5. 종속성 검사: 필요한 모든 라이브러리가 올바르게 패키징되고 런타임에서 액세스할 수 있는지 확인합니다.

실패가 호출 전, 런타임 시작 중 또는 코드 내에서 발생했는지 알면 수정 범위가 훨씬 좁아집니다. 로그를 먼저 확인하고 활성 IAM ID 및 리소스 정책을 증명한 다음, 표시되는 특정 오류에 따라 핸들러, 패키지, 시간 제한, 메모리 및 VPC 설정을 조정합니다.