Lambda 원격 디버깅 작동 방식 시작하기 Lambda 원격 디버깅 액세스 Lambda 원격 디버깅 작업 문제 해결 및 고급 사용 사례

AWS Lambda 원격 디버깅

AWS Toolkit for Visual Studio Code를 사용하면 클라우드에서 실행되는 AWS Lambda 함수를 VS Code에서 직접 디버깅할 수 있습니다. AWS Lambda 원격 디버깅을 사용하면 기존 개발 워크플로를 수정하지 않고도 실행 중인 함수를 검사하고, 중단점을 설정하며, 변수를 검사하고, 단계별 디버깅을 수행할 수 있습니다.

다음 섹션에서는 AWS Toolkit for Visual Studio Code에서 Lambda 원격 디버깅을 사용하는 방법을 설명합니다.

Lambda 원격 디버깅 작동 방식

AWS Toolkit는 추가적인 Lambda 디버깅 계층으로 Lambda 함수를 일시적으로 수정하고 Lambda 간접 호출 제한 시간을 900초로 확장하여 원격 디버깅을 활성화합니다. AWS IoT 보안 터널링을 사용하여 로컬 디버거와 Lambda 런타임 환경 간에 보안 연결이 설정합니다. 이 연결을 사용하면 로컬 코드 중단점을 이용해 원격으로 실행되는 함수를 단계별로 수행할 수 있습니다. 디버깅 세션이 완료되면, 모든 임시 수정 사항이 자동으로 원래 설정으로 되돌아갑니다.

시작하기

지원되는 런타임

Lambda 원격 디버깅에서는 다음 런타임이 지원됩니다.

Python(Amazon Linux 2023)
Java
JavaScript/Node.js(Amazon Linux 2023)

사전 조건

시작하기 전에 다음 사전 요구 사항이 충족되어야 합니다.

AWS Toolkit에 유효한 AWS 자격 증명이 구성되어야 합니다. AWS Toolkit 설치 및 자격 증명 구성에 대한 자세한 내용은 이 사용 설명서의 시작하기 주제를 참조하세요.
AWS 계정에 Lambda 함수가 배포되었습니다. Lambda 함수 배포에 대한 자세한 내용은 AWS Lambda 개발자 안내서의 첫 번째 Lambda 함수 생성 주제를 참조하세요.

함수를 디버깅하려면 적절한 AWS Identity and Access Management (IAM) 정책 및 권한이 있어야 합니다. Lambda 권한에 대한 자세한 내용은 AWS Lambda 개발자 안내서의 AWS Lambda용 AWS 관리형 정책을 참조하세요. 다음은 AWS Toolkit에서 Lambda 원격 디버깅을 사용하는 데 필요한 최소 권한을 포함하는 정책 예시입니다.

참고

원격 디버깅은 AWS AWS IoT 보안 터널링을 통해 활성화됩니다. 이를 통해 로컬 디버거가 Lambda 런타임 환경에 보안 연결을 설정할 수 있습니다.



{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:GetLayerVersion",
        "lambda:UpdateFunctionConfiguration",
        "lambda:InvokeFunction",
        "lambda:PublishVersion",
        "lambda:DeleteFunction",
        "iot:CloseTunnel",
        "iot:OpenTunnel",
        "iot:RotateTunnelAccessToken",
        "iot:ListTunnels"
      ],
      "Resource": "*"
    }
  ]
}

Lambda 원격 디버깅 액세스

AWS Toolkit에는 AWS Explorer 또는 Application Builder 탐색기라는 두 가지 주요 경로가 있습니다. AWS Explorer에서 AWS Lambda 노드를 통해 Lambda 원격 디버깅에 액세스할 수 있습니다. Application Builder 탐색기에서 로컬 AWS SAM 프로젝트를 통해 Lambda 원격 디버깅에 액세스할 수 있습니다.

AWS Explorer에서 Lambda 원격 디버깅에 액세스

VS Code에서 AWS Toolkit 확장을 엽니다.
AWS Toolkit에서 AWS Explorer를 확장하세요.
탐색기에서 Lambda 노드를 확장합니다.
디버깅하려는 함수로 이동한 다음 컨텍스트 메뉴에서 원격 간접 호출 아이콘을 선택하여 원격 간접 호출 구성 화면을 엽니다.

Application Builder 탐색기에서 Lambda 원격 디버깅에 액세스

VS Code에서 AWS Toolkit 확장을 엽니다.
AWS Toolkit에서 애플리케이션 빌더 탐색기를 확장합니다.
탐색기에서 디버깅하려는 Lambda 프로젝트가 포함된 AWS SAM 프로젝트를 확장합니다.
디버깅하려는 배포된 Lambda 함수를 확장합니다.
함수 원격으로 이동한 다음 컨텍스트 메뉴에서 원격 간접 호출 아이콘을 선택하여 원격 간접 호출 구성 화면을 엽니다.

Lambda 원격 디버깅 작업

다음 섹션에서는 AWS Toolkit for Visual Studio Code에서 Lambda 원격 디버깅을 사용하는 방법을 설명합니다.

참고

Lambda 함수는 함수 코드 및 연결된 모든 계층을 포함해 최대 5개의 계층과 합산 250MB의 제한이 있습니다. Lambda 원격 디버깅을 실행하려면 최소 1개의 빈 계층이 필요합니다.

디버깅 세션 설정

시작하기 전에 다음 절차를 완료하여 디버깅 세션을 구성합니다.

AWS Explorer에서 Lambda 원격 디버그 액세스 또는 이전 섹션에 있는 Application Builder 탐색기에서 Lambda 원격 디버그 액세스 절차를 완료하여 원격 호출 구성 메뉴를 엽니다.
원격 간접 호출 구성 메뉴에서 원격 디버깅 확인란을 선택하여 원격 디버깅 속성을 표시합니다.
로컬 핸들러 파일의 로컬 루트 경로를 지정합니다.

참고
로컬 루트 경로는 배포된 Lambda 함수와 일치하는 소스 코드의 위치입니다. Application Builder 탐색기의 배포된 함수에서 작업하는 경우 로컬 루트 경로가 자동으로 감지됩니다.
소스 코드가 로컬에 저장되어 있지 않은 경우 원격 코드 다운로드 버튼을 선택하여 Lambda 함수 소스 코드를 검색합니다. 그러면 VS Code 편집기에서 handler file이 열립니다.
페이로드 섹션에서 테스트 이벤트 데이터를 가져올 위치를 지정합니다.

중단점 설정 및 디버깅

다음 절차를 완료하여 중단점을 설정하고 디버깅을 시작합니다.

VS Code 편집기의 handler file에서 거터-마진을 클릭하여 디버깅을 일시 중지하려는 행 번호에 중단점을 설정합니다.
중단점을 원하는대로 설정했으면, 원격 간접 호출 구성 메뉴로 돌아가 설정이 올바르게 구성되었는지 확인한 다음 원격 호출 버튼을 선택하여 디버깅을 시작합니다.
AWS Toolkit는 디버깅 기능으로 Lambda 함수를 업데이트하고, 디버깅 세션에 대한 보안 터널을 설정하고, 지정된 페이로드로 함수를 간접 호출한 다음, 중단점에 도달하면 프로세스를 일시 중지합니다.
중단점에서 일시 중지했을 시, RUN AND DEBUG 창을 사용하여 VARIABLES, CALL STACK 및 BREAKPOINTS를 확인합니다.

함수 업데이트 및 테스트

빠른 배포로 코드를 수정하고 변경 사항을 테스트하려면 다음 절차를 완료하세요.

디버깅 세션이 활성화된 상태에서 VS Code 편집기에서 handler file의 내용을 변경합니다.
변경 내용 저장(Command+S on macOS,Ctrl+S on Windows)
프롬프트가 표시되면 변경 사항 배포를 진행할지 확인합니다. AWS Toolkit는 수정된 코드로 Lambda 함수를 업데이트합니다.
새 중단점을 설정하고 원격 간접 호출 버튼을 다시 선택하여 변경 사항을 계속 디버깅하고 테스트합니다.

참고
혹은, VS Code 디버깅 컨트롤에서 디버거 연결 옵션을 선택 취소하고 원격 간접 호출 버튼을 선택하여 디버깅 없이 함수를 실행할 수 있습니다.

디버깅 세션 종료

다음 각 옵션은 원격 디버깅 세션을 종료하고 프로젝트에서 디버그 계층을 제거합니다.

원격 간접 호출 구성 화면에서 디버그 설정 제거를 선택합니다.
VS Code 디버깅 제어에서 연결 해제 아이콘을 선택합니다.
VS Code 편집기에서 handler file(을)를 닫습니다.

참고

다음에 유의하세요.

Lambda 디버그 계층은 60초 동안 활동이 없으면 자동으로 제거됩니다. 마지막 간접 호출이 완료되면 시간 계산이 시작됩니다.
디버깅 프로세스 중에 코드형 인프라(IaC) 관리형(AWS SAM, AWS CDK, Terraform) 함수에 코드를 변경한 경우, 로컬 프로젝트에 저장하고 소스 제어 리포지토리를 업데이트하는 것이 좋습니다. 저장되지 않은 변경 사항은 IaC 함수를 재배포할 때 덮어씁니다.
디버깅 목적으로만 임시로 변경한 경우, 소스 제어에서 함수를 재배포하여 프로덕션 코드와 일치하는지 확인할 수 있습니다.

문제 해결 및 고급 사용 사례

디버그 세션이 실패하면 다음의 단계를 완료하여 문제 해결 프로세스를 시작합니다.

AWS Toolkit를 최신 버전으로 업데이트합니다.
원격 간접 호출 구성 웹 보기를 닫고 다시 열어 웹 보기를 새로 고침 합니다.
VS Code를 완전히 닫고 다시 열어 재시작합니다.
VS Code 명령 팔레트를 열고 AWS: Reset Lambda Remote Debugging Snapshot 명령을 입력한 다음, 결과에 명령이 채워지면 해당 명령을 선택하여 Lambda 원격 디버깅 스냅샷을 재설정합니다.
문제를 해결할 수 없는 경우 AWS Toolkit for Visual Studio Code GitHub Issues에 문제를 제출합니다.

고급 사용 사례: 코드 서명 구성

원격 디버깅을 수행하려면 Lambda 함수에 디버그 계층을 연결해야 합니다. 함수에 코드 서명 구성이 활성화 및 적용되는 경우, AWS Toolkit는 디버그 계층을 함수에 자동으로 연결할 수 없습니다.

두 가지 옵션으로 코드 서명 구성 문제를 해결할 수 있습니다.

코드 서명을 일시적으로 제거합니다.
서명된 디버그 계층을 사용합니다.

코드 서명 일시적으로 제거

UntrustedArtifactOnDeployment : Warn 설정으로 코드 서명 구성을 업데이트한 다음 디버깅 프로세스가 완료된 후 Enforced로 다시 활성화합니다.

자세한 내용은 AWS Lambda API 참조의 UpdateCodeSigningConfig 참조 사항을 확인하세요.

서명된 디버그 계층 사용

AWS Toolkit의 Lambda 원격 디버그에서 원격 디버깅 추가 구성 섹션을 확장합니다.
원격 디버그 추가 구성 섹션의 계층 재정의 필드에서 리전 계층 ARN을 복사합니다.
AWS CLI에서 다음 명령을 사용하여 계층 버전 aws lambda get-layer-version-by-arn --arn layer-arn(을)를 다운로드하고 layer-arn을 계층 ARN으로 바꿉니다. 서명된 디버그 계층을 다운로드하는 방법에 대한 자세한 지침은 AWS CLI 명령 참조의 get-layer-version-by-arn 참조를 확인하세요.
코드 서명 구성으로 계층에 서명하고 계정에 게시합니다. 서명 및 게시 지침은 AWS Serverless Application Model 개발자 안내서의 AWS SAM 애플리케이션용 코드 서명 설정 주제를 참조하세요.
계층이 서명되어 계정에 게시되면 Lambda 원격 디버깅의 원격 디버그 추가 구성 섹션으로 돌아가서 계층 재정의 필드에 새 계층 ARN을 입력합니다. 프로세스가 완료되면 Lambda 원격 디버깅은 기본 계층 대신 서명된 계층을 사용합니다.

지원되는 리전

리전이 원격 디버깅을 지원하지 않는 경우 다음 오류가 발생합니다.


Region ${region} doesn't support remote debugging yet

다음은 지원되는 리전 목록입니다.

ap-east-1
ap-northeast-1
ap-northeast-2
ap-south-1
ap-southeast-1
ap-southeast-2
ca-central-1
eu-central-1
eu-north-1
eu-west-1
eu-west-2
eu-west-3
me-central-1
me-south-1
sa-east-1
us-east-1
us-east-2
us-west-1
us-west-2

Lambda RequestEntityTooLargeException

Lambda 함수는 함수 코드 및 연결된 모든 계층을 포함해 최대 5개의 계층과 합산 250MB의 제한이 있습니다. 원격 디버깅 계층은 약 40MB이므로 함수 패키지가 크거나 여러 계층이 있는 경우 함수가 제한을 초과할 수 있습니다. 자세한 내용은 AWS Lambda 개발자 안내서의 Lambda: InvalidParameterValueException 또는 RequestEntityTooLargeException 주제 섹션을 참조하세요.

다음 목록에서는 이 오류를 해결하고 수정하는 방법을 설명합니다.

함수 크기 축소: 함수 코드를 최적화하고 불필요한 종속성을 제거합니다.
미사용 계층 제거: 디버깅 중에 필수적이지 않은 계층을 일시적으로 제거합니다.
외부 종속성 사용: 대규모 종속성을 Amazon S3와 같은 외부 스토리지로 이동하고 런타임에 로드합니다.

IoT 보안 터널링 할당량 초과

다음은 Lambda 원격 디버깅에서 AWS IoT 보안 터널링 연결의 일일 한도에 도달했을 때 발생하는 터널 할당량 초과 오류의 예시입니다.


Error creating/reusing tunnel: LimitExceededException: Exceeded quota of Lambda debugging tunnels

AWS IoT 보안 터널링 연결의 할당량은 다음과 같습니다.

프리 티어 IoT 보안 터널링에는 하루에 10개의 연결이 할당됩니다.
각 터널은 최대 12시간 동안 VS Code 인스턴스 하나를 지원합니다.
할당량은 AWS 계정 기준, 일 단위로 적용됩니다.

AWS IoT 보안 터널링 오류가 발생하면 일일 할당량이 리셋되기를 기다리거나 AWS 지원팀에 문의하여 할당량 제한을 늘려달라고 요청하세요. AWS 지원 연락처 정보는 AWS 지원 연락처 포털을 참조하세요. AWS IoT 보안 터널링에 대한 자세한 내용은 AWS IoT 개발자 안내서의 AWS IoT 보안 터널링을 참조하세요.

소스 맵으로 TypeScript Lambda 함수 디버깅

다음 섹션에서는 소스 맵을 사용해 TypeScript Lambda 함수를 디버깅하는 방법을 설명합니다.

사전 조건

TypeScript Lambda 함수를 디버깅하려면 다음 사전 조건을 충족해야 합니다.

TypeScript는 활성화된 소스 맵 옵션을 준수해야 합니다. 자세한 내용은 VS Code 설명서의 JavaScript 소스 맵 지원 주제를 참조하세요.
인라인 소스 맵으로 작업하려면 모든 변경 사항을 클라우드에 재배포해야 합니다.

구성

AWS Toolkit에서 TypeScript Lambda 함수에 대한 Lambda 원격 디버깅을 구성하려면 다음의 단계를 완료합니다.

AWS Toolkit에서 AWS Explorer를 확장하세요.
탐색기에서 Lambda 노드를 확장합니다.
TypeScript로 구성하려는 함수로 이동한 다음, 컨텍스트 메뉴에서 원격 간접 호출 아이콘을 선택하여 원격 간접 호출 구성 화면을 엽니다.
원격 디버깅 확인란을 선택하여 원격 디버깅을 활성화합니다.
TypeScript handler file가 포함된 디렉터리를 가리켜 로컬 루트 경로를 구성합니다.

참고
TypeScript handler file에서 디버깅 중단점을 설정합니다.
원격 디버그 추가 구성 설정을 확장합니다.
소스 맵 확인란을 선택하여 소스 매핑을 활성화합니다.
출력 파일 필드를 Lambda 함수 복사본의 로컬 디렉터리로 설정합니다.

app.js 및 app.map이 .aws-sam/build/HelloWorldFunction에 있는 경우, 출력 파일 위치를 /Users/user/project/aws-sam/build/HelloWorldFunction/*로 설정합니다.

참고
출력 파일 경로는 절대 경로여야 합니다.
원하는대로 설정했으면 원격 간접 호출 버튼을 선택하여 TypeScript 함수 디버깅을 시작합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

LocalStack을 지원하는 AWS Lambda

Amazon Redshift