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

AWS Lambda 원격 디버깅

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

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

Lambda 원격 디버깅 작동 방식

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

시작하기

지원되는 런타임

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

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

사전 조건

시작하기 전에 다음 사전 조건을 충족해야 합니다.

AWS 도구 키트에 유효한 AWS 자격 증명이 구성되어 있어야 합니다. AWS 도구 키트 설치 및 자격 증명 구성에 대한 자세한 내용은이 사용 설명서의 시작하기 주제를 참조하세요.
Lambda 함수가 AWS 계정에 배포되었습니다. Lambda 함수 배포에 대한 자세한 내용은 AWS Lambda 개발자 안내서의 첫 번째 Lambda 함수 생성 주제를 참조하세요.
함수를 디버깅하려면 적절한 AWS Identity and Access Management (IAM) 정책 및 권한이 있어야 합니다. Lambda 권한에 대한 자세한 내용은 AWS Lambda 개발자 안내서의 주제에 AWS 대한 관리형 정책을 AWS Lambda 참조하세요. 다음은 도구 키트에서 AWS 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 도구 키트에는 탐색기 또는 Application Builder 탐색기라는 AWS 두 가지 주요 경로가 있습니다. AWS 탐색기에서 AWS Lambda 노드를 통해 Lambda 원격 디버깅에 액세스할 수 있습니다. Application Builder 탐색기에서 로컬 AWS SAM 프로젝트를 통해 Lambda 원격 디버깅에 액세스할 수 있습니다.

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

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

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

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

Lambda 원격 디버깅 작업

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

참고

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

디버깅 세션 설정

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

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

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

중단점 설정 및 디버깅

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

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

함수 업데이트 및 테스트

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

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

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

디버깅 세션 종료

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

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

참고

다음에 유의하세요.

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

문제 해결 및 고급 사용 사례

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

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

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

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

코드 서명 구성 문제를 해결하는 두 가지 옵션이 있습니다.

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

일시적으로 코드 서명 제거

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

자세한 내용은 API 참조의 UpdateCodeSigningConfig 참조를 참조하세요. AWS Lambda

서명된 디버그 계층 사용

AWS 도구 키트의 Lambda 원격 디버깅에서 원격 디버깅 추가 구성 섹션을 확장합니다.
원격 디버그 추가 구성 섹션의 계층 재정의 필드에서 리전 계층 ARN을 복사합니다.
에서 다음 명령을 AWS CLI사용하여 계층 버전를 다운로드하고 layer-arn을 계층 ARN으로 aws lambda get-layer-version-by-arn --arn layer-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 도구 키트에서 TypeScript Lambda 함수에 대한 Lambda 원격 디버깅을 구성하려면 다음 단계를 완료합니다.

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

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

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

참고
Out 파일 경로는 절대 경로여야 합니다.
설정이 만족스러우면 원격 호출 버튼을 선택하여 TypeScript 함수 디버깅을 시작합니다.

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

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

문서 규칙

AWS Lambda 함수 작업

AWS Lambda console IDE로