Lambda@Edge 함수 테스트 및 디버깅 - Amazon CloudFront
Lambda@Edge 함수 테스트CloudFront에서 Lambda@Edge 함수 오류 식별잘못된 Lambda@Edge 함수 응답(검증 오류) 문제 해결Lambda@Edge 함수 실행 오류 문제 해결 Lambda@Edge 리전 확인계정이 CloudWatch로 로그를 푸시하는지 확인

Lambda@Edge 함수 테스트 및 디버깅

이 주제에는 Lambda@Edge 함수 테스트 및 디버깅에 대한 전략을 설명하는 단원이 있습니다. 의도한 작업을 완료하는지 확인하기 위해서는 Lambda@Edge 함수 코드를 단독으로 테스트해야 하고, 함수가 CloudFront와 함께 잘 작동하는지 확인하기 위해서는 통합 테스트를 수행해야 합니다.

통합 테스트 중 또는 함수 배포 완료 후 HTTP 5xx 오류 등과 같은 CloudFront 오류를 디버깅해야 할 수 있습니다. Lambda 함수에서 반환되는 잘못된 응답, 함수 실행 시 발생하는 실행 오류 또는 Lambda 서비스의 실행 조절로 인한 오류 등이 있을 수 있습니다. 이 주제의 단원에서는 이러한 문제가 어떤 유형의 실패인지 확인한 다음 각 문제를 해결하기 위해 수행할 수 있는 단계에 대해 설명합니다.

참고

오류를 해결하기 위해 CloudWatch 로그 파일 또는 지표를 검토할 때 함수가 실행된 위치에 가장 가까운 AWS 리전에 로그 파일 또는 지표가 표시 또는 저장된다는 점에 유의하세요. 예를 들어, 영국 내 사용자가 있는 웹 사이트 또는 웹 애플리케이션이 있고 배포와 연결된 Lambda 함수가 있는 경우 런던 AWS 리전 리전에 대한 CloudWatch 지표 또는 로그 파일을 볼 수 있도록 리전을 변경해야 합니다. 자세한 내용은 Lambda@Edge 리전 확인 단원을 참조하십시오.

Lambda@Edge 함수 테스트

Lambda 함수 테스트에는 독립 실행형 테스트와 통합 테스트, 이렇게 두 가지 단계가 있습니다.

독립 실행형 기능 테스트

CloudFront에 Lambda 함수를 추가하기 전에 Lambda 콘솔의 테스트 기능을 사용하거나 다른 방법을 사용하여 기능을 먼저 테스트해야 합니다. Lambda 콘솔에서 테스트에 대한 자세한 내용은 AWS Lambda 개발자 안내서에서 콘솔로 Lambda 함수 생성의 Lambda 함수를 호출하고 결과, 로그 및 지표 확인 섹션을 참조하세요.

CloudFront에서 함수의 작동 상태를 보기 위한 테스트

함수가 배포와 연결되어 있고 CloudFront 이벤트를 기반으로 실행되는 경우에는 통합 테스트를 반드시 완료해야 합니다. 함수가 올바른 이벤트 발생 시 실행되고 CloudFront에 대해 올바른 응답을 반환하는지 확인합니다. 예를 들어, 이벤트 구조가 올바른지, 유효한 헤더만 포함되어 있는지 등을 확인합니다.

Lambda 콘솔에서 함수의 통합 테스트를 반복하는 것처럼 코드를 수정하거나 함수를 호출하는 CloudFront 트리거를 변경할 때 Lambda@Edge 자습서의 단계를 참조하세요. 예를 들어, 본 자습서의 단계(4단계: 함수를 실행할 CloudFront 트리거 추가)에서 설명하는 것처럼 다양한 버전의 함수에서 작동하는지 확인합니다.

함수를 변경하고 배포할 때 업데이트된 함수 및 CloudFront 트리거가 모든 리전에서 복제되는 데 몇 분 정도 걸릴 수 있습니다. 일반적으로 몇 분이면 되지만 최대 15분까지 걸릴 수 있습니다.

CloudFront 콘솔로 이동하여 해당 배포를 보고 복제가 완료되었는지 확인할 수 있습니다.

복제본 배포가 완료되었는지 확인하려면

  1. https://console.aws.amazon.com/cloudfront/v4/home에서 CloudFront 콘솔을 엽니다.

  2. 배포 이름을 선택합니다.

  3. 배포 상태가 진행 중에서 다시 배포 완료로 바뀌었는지 확인합니다. 이것은 함수가 복제되었다는 의미입니다. 이제 다음 단원의 단계에 따라 함수가 작동하는지 확인합니다.

콘솔의 테스트는 함수의 로직만 확인하며, Lambda@Edge에 고유한 모든 서비스 할당량(이전에는 제한이라고 함)은 적용하지 않습니다.

CloudFront에서 Lambda@Edge 함수 오류 식별

함수 로직이 올바르게 작동하는지 확인한 후 CloudFront에서 함수 실행 시 HTTP 5xx 오류가 나타날 수 있습니다. HTTP 5xx 오류는 여러 가지 이유로 반환될 수 있습니다. 여기에는 Lambda 함수 오류 또는 CloudFront의 다른 문제가 포함될 수 있습니다.

  • Lambda@Edge 함수를 사용하는 경우 CloudFront 콘솔의 그래프를 사용하여 오류의 원인을 추적하고 문제를 해결할 수 있습니다. 예를 들어, HTTP 5xx 오류가 CloudFront 또는 Lambda 함수에 의해 발생한 것인지를 확인한 다음 특정 함수에 대해 관련 로그 파일을 검토하여 문제를 조사할 수 있습니다.

  • CloudFront에서 일반적인 HTTP 오류 문제를 해결하려면 오리진의 오류 응답 문제 해결 주제의 문제 해결 단계를 참조하세요.

CloudFront에서 Lambda@Edge 함수 오류를 일으키는 원인

Lambda 함수가 HTTP 5xx 오류를 일으키는 원인에는 여러 가지가 있으며, 수행해야 할 문제 해결 단계는 오류 유형에 따라 달라집니다. 오류는 다음과 같이 분류할 수 있습니다.

Lambda 함수 실행 오류

함수에 처리되지 않은 예외가 있거나 코드에 오류가 있기 때문에 CloudFront가 Lambda에서 응답을 받지 못한 경우 실행 오류가 발생합니다. 예: 코드에 콜백이 포함된 경우(오류) 자세한 내용은 AWS Lambda 개발자 안내서의 Lambda 함수 오류를 참조하세요.

잘못된 Lambda 함수 응답이 CloudFront로 반환됨

함수 실행 후 CloudFront가 Lambda에서 응답을 수신했습니다. 응답의 객체 구조가 Lambda@Edge 이벤트 구조를 따르지 않거나 응답에 잘못된 헤더 또는 기타 잘못된 필드가 포함되어 있는 경우 오류가 반환됩니다.

Lambda 서비스 할당량(이전에는 제한이라고 함)으로 인해 CloudFront에서의 실행이 제한됨

Lambda 서비스는 각 리전에서 실행을 조절하는데 할당량을 초과하면 오류를 반환합니다.

실패 유형을 결정하는 방법

디버깅할 때 집중할 위치를 결정하고 CloudFront에서 반환한 오류를 해결하려면 CloudFront에서 HTTP 오류가 반환된 이유를 파악하는 것이 좋습니다. 시작하려면 AWS Management Console의 CloudFront 콘솔에 있는 모니터링 섹션에 제공된 그래프를 사용합니다. CloudFront 콘솔의 모니터링(Monitoring) 섹션에서 그래프를 보는 방법에 대한 자세한 내용은 Amazon CloudWatch를 사용한 CloudFront 지표 모니터링 단원을 참조하세요.

다음 그래프는 오리진 또는 Lambda 함수로 오류를 반환하는지 여부를 추적하고 Lambda 함수의 오류일 경우 문제 유형의 범위를 좁히려 할 때 특히 유용합니다.

오류 발생율 그래프

각 배포의 개요 탭에서 볼 수 있는 그래프 중에는 오류 발생율 그래프가 있습니다. 이 그래프는 배포에 들어오는 총 요청의 백분율로 오류 발생율을 표시합니다. 그래프는 총 오류 발생율, 총 4xx 오류, 총 5xx 오류 및 Lambda 함수의 총 5xx 오류를 보여줍니다. 오류 유형 및 볼륨에 따라 원인을 조사하고 문제를 해결할 수 있는 단계를 수행할 수 있습니다.

CloudFront 배포에 대한 오류 발생율 그래프

  • Lambda 오류가 표시되면 함수가 반환하는 특정 유형의 오류를 확인하여 추가 조사를 수행할 수 있습니다. Lambda@Edge errors(Lambda@Edge 오류) 탭에는 함수 오류를 유형별로 분류하여 특정 함수에 대한 문제를 찾아낼 수 있는 그래프가 포함되어 있습니다.

  • CloudFront 오류가 표시되면 문제를 해결하고 오리진 오류를 수정하거나 CloudFront 구성을 변경할 수 있습니다. 자세한 내용은 오리진의 오류 응답 문제 해결 단원을 참조하십시오.

실행 오류 및 잘못된 함수 응답 그래프

Lambda@Edge errors(Lambda@Edge 오류) 탭에는 특정 배포에 대한 Lambda@Edge 오류를 유형별로 분류하는 그래프가 포함되어 있습니다. 예를 들어, 한 그래프는 모든 실행 오류를 AWS 리전별로 표시합니다.

문제를 쉽게 해결할 수 있도록 특정 함수에 대한 로그 파일을 열고 리전별로 검토하여 특정 문제를 찾을 수 있습니다.

리전별로 특정 함수의 로그 파일을 보려면

  1. Lambda@Edge 오류 탭의 관련 Lambda@Edge 함수에서 함수 이름을 선택한 다음 지표 보기를 선택합니다.

  2. 그런 다음, 함수 이름이 있는 페이지의 오른쪽 상단 모서리에서 함수 로그 보기를 선택한 다음 리전을 선택합니다.

    예를 들어 미국 서부(오레곤) 리전에 대한 오류 그래프에 문제가 있는 경우 드롭다운 목록에서 해당 리전을 선택합니다. 그러면 Amazon CloudWatch 콘솔이 열립니다.

  3. 해당 리전의 CloudWatch 콘솔에서 로그 스트림 아래의 로그 스트림을 선택하여 함수에 대한 이벤트를 확인합니다.

또한 이 장의 다음 단원에서 오류 해결 및 수정에 대한 추가 권장 사항을 읽으십시오.

제한 그래프

Lambda@Edge errors(Lambda@Edge 오류) 탭에는 제한 그래프도 있습니다. 경우에 따라 리전 동시성 할당량(이전에는 제한이라고 함)에 도달하면 Lambda 서비스가 리전별로 함수 호출을 제한합니다. 제한 초과 오류가 발생한 경우는 리전에서의 실행에 대해 Lambda 서비스가 부과한 할당량에 도달한 것입니다. 이러한 할당량을 늘리기 위한 요청 방법을 비롯한 자세한 내용은 Lambda@Edge에 대한 할당량 단원을 참조하세요.

Lambda@Edge 함수 실행에 대한 제한 그래프

이 정보를 사용하여 HTTP 오류 문제를 해결하는 방법에 대한 예제는 AWS에서 콘텐츠 전송을 디버깅하기 위한 네 가지 단계를 참조하세요.

잘못된 Lambda@Edge 함수 응답(검증 오류) 문제 해결

Lambda 확인 오류가 문제라고 파악한 경우는 Lambda 함수가 CloudFront에 잘못된 응답을 반환하고 있다는 의미입니다. 이 단원의 지침에 따라 함수를 검토하는 단계를 수행한 다음 응답이 CloudFront 요구 사항을 따르는지 확인하세요.

CloudFront는 다음 두 가지 방법으로 Lambda 함수의 응답을 확인합니다.

  • Lambda 응답은 필수 객체 구조를 따라야 합니다. 잘못된 객체 구조의 예에는 구문 분석이 불가능한 JSON, 필수 필드 누락 및 응답에 포함된 잘못된 객체 등이 있습니다. 자세한 내용은 Lambda@Edge 이벤트 구조 단원을 참조하십시오.

  • 응답에는 올바른 객체만 포함되어 있어야 합니다. 응답에 올바른 객체가 포함되어 있는데 그 값이 지원되지 않는 경우에는 오류가 발생합니다. 등록된 헤더 또는 읽기 전용 헤더를 추가 또는 업데이트하는 경우(엣지 함수에 대한 제한 사항 참조), 최대 본문 크기 초과(Lambda@Edge Errors 주제에서 생성된 응답 크기 제한 참조) 및 잘못된 문자 또는 값(Lambda@Edge 이벤트 구조 참조) 등을 예로 들 수 있습니다.

Lambda가 CloudFront에 대해 유효하지 않은 응답을 반환하면 CloudFront가 Lambda 함수가 실행된 리전의 CloudWatch에 푸시하는 로그 파일에 오류 메시지가 기록됩니다. 잘못된 응답이 있는 경우 CloudWatch로 로그 파일을 보내는 것은 기본 동작입니다. 그러나 Lambda 함수를 릴리스하기 전에 CloudFront와 연결한 경우에는 함수에 대해 활성화되지 않을 수 있습니다. 자세한 내용은 이 주제 뒷부분에 나오는 계정이 CloudWatch로 로그를 푸시하는지 확인을 참조하세요.

CloudFront는 배포와 연결된 로그 그룹 내에서 함수가 실행되는 위치에 해당하는 리전으로 로그 파일을 푸시합니다. 로그 그룹의 형식은 /aws/cloudfront/LambdaEdge/DistributionId인데, 여기서 DistributionId는 배포 ID입니다. CloudWatch 로그 파일을 찾을 수 있는 리전을 확인하려면 이 주제 뒷부분에 나오는 Lambda@Edge 리전 확인을 참조하세요.

오류를 재현할 수 있는 경우 오류가 발생하는 새로운 요청을 생성한 다음 실패한 CloudFront 응답(X-Amz-Cf-Id 헤더)에서 해당 요청 ID를 찾아 로그 파일에서 단일 실패를 확인할 수 있습니다. 로그 파일 항목에는 오류가 반환된 이유를 파악하는 데 도움이 되는 정보가 포함되어 있고 해당하는 Lambda 요청 ID가 나열되어 있기 때문에 단일 요청의 컨텍스트 내에서 근본 원인을 분석할 수 있습니다.

오류가 간헐적으로 발생하는 경우에는 CloudFront 액세스 로그를 사용하여 실패한 요청의 요청 ID를 찾은 다음 CloudWatch 로그에서 해당하는 오류 메시지를 검색할 수 있습니다. 자세한 내용은 앞의 실패 유형 확인 단원을 참조하십시오.

Lambda@Edge 함수 실행 오류 문제 해결

Lambda 실행 오류가 문제인 경우에는 Lambda 함수에 대한 로깅 문을 생성해 CloudWatch 로그 파일에 CloudFront에서 함수의 실행을 모니터링하는 메시지를 작성한 다음 예상대로 작동하는지 확인하면 도움이 될 수 있습니다. 그런 다음 CloudWatch 로그 파일에서 해당 문을 검색해 함수가 작동 중인지 확인할 수 있습니다.

참고

Lambda@Edge 함수를 변경하지 않은 경우에도 Lambda 함수 실행 환경에 대한 업데이트가 영향을 줄 수 있으며, 실행 오류가 반환될 수 있습니다. 테스트 및 이후 버전으로의 마이그레이션에 대한 자세한 내용은 AWS Lambda 및 AWS Lambda@Edge 실행 환경에 대해 예정된 업데이트를 참조하세요.

Lambda@Edge 리전 확인

Lambda@Edge 함수가 트래픽을 수신하는 리전을 보려면 AWS Management Console에서 CloudFront 콘솔의 함수에 대한 지표를 확인하세요. 지표는 각 AWS 리전별로 표시됩니다. 동일한 페이지에서 리전을 선택하고 해당 리전의 로그 파일을 확인하여 문제를 조사할 수 있습니다. CloudFront에서 Lambda 함수를 실행할 때 생성된 로그 파일을 확인하려면 올바른 AWS 리전의 CloudWatch Logs 파일을 검토해야 합니다.

CloudFront 콘솔의 모니터링(Monitoring) 섹션에서 그래프를 보는 방법에 대한 자세한 내용은 Amazon CloudWatch를 사용한 CloudFront 지표 모니터링 단원을 참조하세요.

계정이 CloudWatch로 로그를 푸시하는지 확인

기본적으로 CloudFront는 잘못된 Lambda 함수 응답 로깅을 활성화하고 Lambda@Edge의 서비스 연결 역할 중 하나를 수행해 로그 파일을 CloudWatch로 푸시합니다. 잘못된 Lambda 함수 응답 로그 기능이 활성화되기 전에 CloudFront에 Lambda@Edge 함수를 추가한 경우에는 예를 들어, CloudFront 트리거 추가 등과 같이 다음에 Lambda@Edge 구성을 업데이트하는 경우 로깅이 활성화됩니다.

다음을 수행해 계정에 대해 CloudWatch로 로그 파일 푸시 기능이 활성화되어 있는지 확인할 수 있습니다.

  • CloudWatch에 로그가 나타나는지 확인 Lambda@Edge 함수가 실행된 리전에서 로그 파일을 확인해야 합니다. 자세한 내용은 Lambda@Edge 리전 확인 단원을 참조하십시오.

  • IAM의 계정에 관련 서비스 연결 역할이 있는지 확인. 이렇게 하려면 https://console.aws.amazon.com/iam/에서 IAM 콘솔을 연 다음 역할(Roles)을 선택해 계정에 대한 서비스 연결 역할 목록을 봅니다. AWSServiceRoleForCloudFrontLogger 역할을 찾습니다.