Lambda 확장 API를 사용하여 확장 생성

Lambda 함수 작성자는 익스텐션을 사용하여 모니터링, 관찰, 보안 및 거버넌스를 위해 선호하는 도구와 Lambda를 통합합니다. 함수 작성자는 AWS, AWS 파트너 및 오픈 소스 프로젝트의 익스텐션을 사용할 수 있습니다. 익스텐션 사용에 대한 자세한 내용은 AWS Lambda 컴퓨팅 블로그의 AWS 익스텐션 소개를 참조하세요. 이 섹션에서는 Lambda 확장 API, Lambda 실행 환경 수명 주기 및 Lambda 확장 API 참조를 사용하는 방법을 설명합니다.

익스텐션 작성자는 Lambda 익스텐션 API를 사용하여 Lambda 실행 환경과 완전히 통합할 수 있습니다. 익스텐션은 함수 및 실행 환경 수명 주기 이벤트에 등록할 수 있습니다. 이러한 이벤트에 대한 응답으로 새 프로세스를 시작하고, 논리를 실행하고, Lambda 수명 주기의 모든 단계(초기화, 호출 및 종료)를 관리하고 참여할 수 있습니다. 또한 런타임 로그 API를 사용하여 로그 스트림을 수신할 수 있습니다.

익스텐션은 실행 환경에서 독립 프로세스로 실행되며 함수 호출이 완전히 처리된 후에도 계속 실행됩니다. 익스텐션은 프로세스로 실행되므로 함수와 다른 언어로 작성할 수 있습니다. 컴파일된 언어를 사용하여 익스텐션을 구현하는 것이 좋습니다. 이 경우 익스텐션은 지원되는 런타임과 호환되는 독립형 바이너리입니다. 모든 Lambda 런타임은 익스텐션을 지원합니다. 컴파일되지 않은 언어를 사용하는 경우 호환되는 런타임을 익스텐션에 포함해야 합니다.

Lambda는 내부 익스텐션도 지원합니다. 내부 익스텐션은 런타임 프로세스에서 별도의 스레드로 실행됩니다. 런타임은 내부 익스텐션을 시작하고 중지합니다. Lambda 환경과 통합하는 다른 방법은 언어별 환경 변수 및 래퍼 스크립트를 사용하는 것입니다. 이 방법을 통해 런타임 환경을 구성하고 런타임 프로세스의 시작 동작을 수정할 수 있습니다.

두 가지 방법으로 익스텐션을 함수에 추가할 수 있습니다. .zip 파일 아카이브로 배포된 함수의 경우 익스텐션을 계층으로 배포합니다. 컨테이너 이미지로 정의된 함수의 경우 익스텐션을 컨테이너 이미지에 추가합니다.

Lambda 실행 환경 수명 주기

실행 환경의 수명 주기에는 다음 단계가 포함됩니다.

각 단계는 Lambda에서 런타임 및 등록된 모든 익스텐션에 전송하는 이벤트로 시작됩니다. 런타임 및 각 익스텐션이 Next API 요청을 전송하여 완료 신호를 보냅니다. 각 프로세스가 완료되고 대기 중인 이벤트가 없으면 Lambda는 실행 환경을 중지합니다.

초기화 단계

Extension init 단계 중에 이벤트를 수신하려면 각 익스텐션은 Lambda에 등록해야 합니다. Lambda는 익스텐션의 전체 파일 이름을 사용하여 익스텐션이 부트스트랩 시퀀스를 완료했는지 확인합니다. 따라서 각 Register API 호출에는 익스텐션의 전체 파일 이름이 있는 Lambda-Extension-Name 헤더를 포함해야 합니다.

각 함수에 최대 10개의 익스텐션을 등록할 수 있습니다. 이 제한은 Register API 호출을 통해 적용됩니다.

각 익스텐션이 등록되면 Lambda는 Runtime init 단계를 시작합니다. 런타임 프로세스는 functionInit를 호출하여 Function init 단계를 시작합니다.

Init 단계는 런타임 및 등록된 각 익스텐션이 Next API 요청을 전송하여 완료를 나타낸 후에 완료됩니다.

호출 단계

Next API 요청에 대한 응답으로 Lambda 함수가 호출되면 Lambda는 런타임과 Invoke 이벤트에 등록된 각 익스텐션에 Invoke 이벤트를 전송합니다.

호출하는 동안 외부 익스텐션은 함수와 동시에 실행됩니다. 또한 함수가 완료된 후에도 외부 익스텐션이 계속 실행됩니다. 따라서 진단 정보를 캡처하거나 로그, 지표 및 추적 정보를 선택한 위치로 보낼 수 있습니다.

런타임에서 함수 응답을 수신한 후 Lambda는 익스텐션이 여전히 실행 중이더라도 클라이언트에 대한 응답을 반환합니다.

Invoke 단계는 런타임 및 모든 익스텐션이 Next API 요청을 전송하여 완료되었음을 알린 후에 종료됩니다.

이벤트 페이로드: 런타임(및 Lambda 함수)으로 전송되는 이벤트에는 전체 요청, 헤더(예: RequestId) 및 페이로드가 포함됩니다. 각 익스텐션으로 전송되는 이벤트에는 이벤트 내용을 설명하는 메타데이터가 포함됩니다. 이 수명 주기 이벤트에는 이벤트 유형, 함수가 시간 초과되는 시간(deadlineMs), requestId, 호출된 함수의 Amazon 리소스 이름(ARN) 및 추적 헤더가 포함됩니다.

함수 이벤트 본문에 액세스하려는 익스텐션은 익스텐션과 통신하는 런타임 내 SDK를 사용할 수 있습니다. 함수 개발자는 런타임 내 SDK를 사용하여 함수가 호출될 때 익스텐션에 페이로드를 전송합니다.

다음은 페이로드의 예입니다.

{
    "eventType": "INVOKE",
    "deadlineMs": 676051,
    "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
    "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
    "tracing": {
        "type": "X-Amzn-Trace-Id",
        "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
    }
 }          

기간 제한: 함수의 제한 시간 설정은 전체 Invoke 단계의 기간을 제한합니다. 예를 들어 함수 제한 시간을 360초로 설정하면 함수와 모든 익스텐션이 360초 내에 완료되어야 합니다. 독립적인 호출 후 단계는 없습니다. 기간은 런타임 및 모든 확장의 호출이 완료되는 데 걸리는 총 시간이며 함수와 모든 확장의 실행이 완료될 때까지 계산되지 않습니다.

성능 영향 및 익스텐션 오버헤드: 익스텐션은 함수 성능에 영향을 줄 수 있습니다. 익스텐션 작성자는 익스텐션이 성능에 미치는 영향을 제어할 수 있습니다. 예를 들어 익스텐션이 컴퓨팅 집약적 작업을 수행하는 경우 함수 소요 시간이 늘어납니다. 익스텐션과 함수 코드가 동일한 CPU 리소스를 공유하기 때문입니다. 또한 함수 호출이 완료된 후 익스텐션에서 대규모 연산을 수행하는 경우 모든 익스텐션이 완료되었음을 알릴 때까지 Invoke 단계가 계속되므로 함수 소요 시간이 늘어납니다.

Invoke 단계에서 익스텐션에 의한 성능 영향을 식별할 수 있도록 Lambda는 PostRuntimeExtensionsDuration 지표를 출력합니다. 이 지표는 런타임 Next API 요청과 마지막 익스텐션 Next API 요청 사이의 누적 시간을 측정합니다. 사용된 메모리 증가를 측정하려면 MaxMemoryUsed 지표를 사용합니다. 함수 지표에 대한 자세한 내용은 Lambda 함수에 대한 지표 보기 섹션을 참조하세요.

함수 개발자는 다양한 버전의 함수를 나란히 실행하여 특정 익스텐션의 영향을 파악할 수 있습니다. 익스텐션 작성자는 함수 개발자가 적합한 익스텐션을 쉽게 선택할 수 있도록 예상되는 리소스 소비를 게시하는 것이 좋습니다.

종료 단계

Lambda는 런타임을 종료하려고 할 때 Shutdown을 등록된 각 외부 익스텐션에 전송합니다. 익스텐션은 이 시간 동안 최종 정리 작업을 수행할 수 있습니다. Shutdown 이벤트는 Next API 요청에 대한 응답으로 전송됩니다.

기간 제한: Shutdown 단계의 최대 기간은 등록된 익스텐션 구성에 따라 다릅니다.

함수에 외부 익스텐션이 있는 경우 Lambda는 런타임 프로세스가 정상 종료를 수행하도록 최대 300밀리초(내부 익스텐션이 있는 런타임의 경우 500밀리초)를 예약합니다. Lambda는 외부 익스텐션이 종료되도록 2,000밀리초 제한에서 남은 시간을 할당합니다.

런타임 또는 익스텐션이 제한 시간 내에 Shutdown 이벤트에 응답하지 않는 경우 Lambda는 SIGKILL 신호를 사용하여 프로세스를 종료합니다.

이벤트 페이로드: Shutdown 이벤트에는 종료 이유와 남은 시간(밀리초)이 포함됩니다.

shutdownReason에는 다음과 같은 값이 포함됩니다.

{ 
  "eventType": "SHUTDOWN", 
  "shutdownReason": "reason for shutdown", 
  "deadlineMs": "the time and date that the function times out in Unix time milliseconds" 
}        
      

권한 및 구성

익스텐션은 Lambda 함수와 동일한 실행 환경에서 실행됩니다. 익스텐션은 CPU, 메모리, /tmp 디스크 스토리지와 같은 리소스를 함수와 공유합니다. 또한 익스텐션은 함수와 동일한 AWS Identity and Access Management(IAM) 역할 및 보안 컨텍스트를 사용합니다.

파일 시스템 및 네트워크 액세스 권한: 익스텐션은 함수 런타임과 동일한 파일 시스템 및 네트워크 이름 네임스페이스에서 실행됩니다. 따라서 익스텐션은 해당 운영 체제와 호환되어야 합니다. 익스텐션에 추가 아웃바운드 네트워크 트래픽 규칙이 필요한 경우 이러한 규칙을 함수 구성에 적용해야 합니다.

환경 변수: 익스텐션은 런타임 프로세스와 관련된 다음 변수를 제외하고 함수의 환경 변수에 액세스할 수 있습니다.

장애 처리

초기화 오류: 익스텐션에 오류가 발생하면 Lambda는 실행 환경을 다시 시작하여 일관된 동작을 적용하고 익스텐션에 대해 빠른 실패(fast fail)를 장려합니다. 또한 일부 고객의 경우 익스텐션이 로깅, 보안, 거버넌스 및 텔레메트리 수집과 같은 미션 크리티컬한 요구 사항을 충족해야 합니다.

호출 오류(예: 메모리 부족, 함수 시간 초과): 익스텐션은 런타임과 리소스를 공유하므로 메모리 부족의 영향을 받습니다. 런타임에 오류가 발생하면 모든 익스텐션과 런타임 자체가 Shutdown 단계에 참여합니다. 또한 런타임은 현재 호출의 일부로 자동으로 다시 시작되거나 지연된 재초기화 메커니즘을 통해 다시 시작됩니다.

함수 시간 초과 또는 런타임 오류와 같은 오류가 발생하면 Invoke 시 Lambda 서비스가 재설정을 수행합니다. 재설정은 Shutdown 이벤트처럼 동작합니다. 먼저 Lambda는 런타임을 종료한 다음 등록된 각 외부 익스텐션에 Shutdown 이벤트를 전송합니다. 이벤트에는 종료 이유가 포함됩니다. 이 환경이 새 호출에 사용되는 경우 익스텐션 및 런타임은 다음 호출의 일부로 다시 초기화됩니다.

이전 다이어그램에 대한 자세한 설명은 호출 단계 중 실패을 참조하십시오.

익스텐션 로그: Lambda가 익스텐션의 로그 출력을 CloudWatch Logs에 보냅니다. Lambda는 Init 시 각 익스텐션에 대한 추가 로그 이벤트도 생성합니다. 로그 이벤트에는 성공 시 이름 및 등록 기본 설정(이벤트, 구성)과 실패 시 실패 이유가 기록됩니다.

익스텐션 문제 해결

익스텐션 API 참조

익스텐션 API 버전 2020-01-01에 대한 OpenAPI 사양은 extensions-api.zip에서 사용할 수 있습니다.

AWS_LAMBDA_RUNTIME_API 환경 변수에서 API 엔드포인트의 값을 검색할 수 있습니다. Register 요청을 보내려면 각 API 경로 앞에 접두사 2020-01-01/을 사용합니다. 예:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register 

등록

Extension init 중에 이벤트를 수신하려면 모든 익스텐션은 Lambda에 등록해야 합니다. Lambda는 익스텐션의 전체 파일 이름을 사용하여 익스텐션이 부트스트랩 시퀀스를 완료했는지 확인합니다. 따라서 각 Register API 호출에는 익스텐션의 전체 파일 이름이 있는 Lambda-Extension-Name 헤더를 포함해야 합니다.

내부 익스텐션은 런타임 프로세스에 의해 시작 및 중지되므로 Shutdown 이벤트에 등록할 수 없습니다.

경로 – /extension/register

메서드 – POST

요청 헤더

{
    'events': [ 'INVOKE', 'SHUTDOWN']
}             

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler"
}               

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

Next

익스텐션은 Next API 요청을 전송하여 다음 이벤트(Invoke 이벤트 또는 Shutdown 이벤트가 될 수 있음)를 수신합니다. 응답 본문에는 이벤트 데이터가 포함된 JSON 문서인 페이로드가 포함되어 있습니다.

익스텐션은 Next API 요청을 전송하여 새 이벤트를 수신할 준비가 되었음을 알립니다. 이는 차단 호출입니다.

반환할 이벤트가 발생할 때까지 일정 기간 동안 익스텐션이 일시 중단될 수 있으므로 GET 호출에 시간 제한을 설정하지 마세요.

경로 – /extension/event/next

매서드 – GET

초기화 오류

익스텐션은 이 메서드를 사용하여 Lambda에 초기화 오류를 보고합니다. 익스텐션이 등록된 후 초기화에 실패할 경우 이 메서드를 호출합니다. Lambda가 오류를 수신하면 더 이상 API 호출이 성공하지 못합니다. 익스텐션은 Lambda로부터 응답을 수신한 후에 종료되어야 합니다.

경로 – /extension/init/error

메서드 – POST

이 필드는 다음과 같은 구조의 JSON 객체입니다.

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda는 errorType에 대한 모든 값을 허용합니다.

다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

종료 오류

익스텐션은 종료 전에 이 메서드를 사용하여 Lambda에 오류를 보고합니다. 예기치 않은 오류가 발생하면 이 메서드를 호출합니다. Lambda가 오류를 수신하면 더 이상 API 호출이 성공하지 못합니다. 익스텐션은 Lambda로부터 응답을 수신한 후에 종료되어야 합니다.

경로 – /extension/exit/error

메서드 – POST

이 필드는 다음과 같은 구조의 JSON 객체입니다.

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda는 errorType에 대한 모든 값을 허용합니다.

다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}