Lambda 지속 함수 만들기

Lambda 지속 함수를 시작하려면 Lambda 콘솔을 사용해서 지속 함수를 만들어요. 몇 분 안에 단계(steps)와 대기(waits)를 사용해 체크포인트 기반 실행을 보여주는 지속 함수를 만들고 배포할 수 있어요.

또한 AWS CLI나 인프라스트럭처 코드(IaC)를 사용해서 지속 함수를 만들 수도 있어요.

튜토리얼을 진행하면서 DurableContext 객체 사용, 단계로 체크포인트 만들기, 대기로 실행 일시 중지 같은 지속 함수의 기본 개념을 배우게 돼요. 대기 후 함수가 재개될 때 리플레이가 어떻게 작동하는지도 배우게 돼요.

간단하게 유지하기 위해 이 튜토리얼은 Python 또는 Node.js 런타임을 사용해서 함수를 만드는 방법을 보여줘요. 이 해석형 언어를 사용하면 콘솔의 기본 제공 코드 편집기에서 함수 코드를 직접 편집할 수 있어요.

참고 지속 함수는 현재 Python, Node.js(JavaScript/TypeScript), Java 런타임과 컨테이너 이미지(OCI)를 지원해요. 지원되는 런타임 버전과 컨테이너 이미지 옵션의 전체 목록은 지속 함수용 지원 런타임을 참고하세요. Lambda와 함께 컨테이너 이미지를 사용하는 방법에 대한 자세한 내용은 Lambda 개발자 안내서의 Lambda 컨테이너 이미지 만들기를 참고하세요.

팁 서버리스 솔루션을 빌드하는 방법을 배우려면 Serverless 개발자 안내서를 확인하세요.

출처: AWS Lambda 개발자 안내서

본문

콘솔로 Lambda 지속 함수 만들기

이 예시에서 지속 함수는 자동 체크포인트 방식으로 여러 단계를 거쳐 주문을 처리해요. 함수는 주문 ID를 포함한 JSON 객체를 받아 주문을 검증하고, 결제를 처리하고, 주문을 확인해요. 각 단계는 자동으로 체크포인트되므로 함수가 중단되면 마지막으로 완료된 단계부터 재개돼요.

또한 함수는 외부 확인을 기다리는 것을 시뮬레이션하기 위해 짧은 시간 동안 실행을 일시 중지하는 대기 연산도 보여줘요.

콘솔로 지속 함수를 만들려면

Lambda 콘솔의 함수 페이지를 엽니다.
함수 생성(Create function)을 선택합니다.
처음부터 작성(Author from scratch)을 선택합니다.
기본 정보(Basic information) 창에서 함수 이름(Function name)에 myDurableFunction을 입력합니다.
런타임(Runtime)에서 Node.js 24 또는 Python 3.14 중 하나를 선택합니다.
지속 실행 활성화(Enable durable execution)를 선택합니다.

Lambda는 체크포인트 작업(lambda:CheckpointDurableExecution 및 lambda:GetDurableExecutionState)에 대한 권한을 포함한 실행 역할로 지속 함수를 만들어요.

참고 Lambda 런타임에는 Durable Execution SDK가 포함되어 있어 종속성을 패키징하지 않고도 지속 함수를 테스트할 수 있어요. 하지만 프로덕션의 경우 배포 패키지에 SDK를 포함하는 것을 권장해요. 이렇게 하면 버전 일관성이 보장되고 함수에 영향을 줄 수 있는 잠재적 런타임 업데이트를 피할 수 있어요.

콘솔의 기본 제공 코드 편집기를 사용해서 지속 함수 코드를 추가하세요.

Node.js

콘솔에서 코드를 수정하려면

코드(Code) 탭을 선택합니다.

콘솔의 기본 제공 코드 편집기에서 Lambda가 만든 함수 코드가 보일 거예요. 코드 편집기에 index.mjs 탭이 보이지 않으면 다음 다이어그램과 같이 파일 탐색기에서 index.mjs를 선택하세요.

다음 코드를 index.mjs 탭에 붙여넣어 Lambda가 만든 코드를 대체합니다.

import {
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

export const handler = withDurableExecution(
  async (event, context) => {
    const orderId = event.orderId;

    // Step 1: Validate order
    const validationResult = await context.step(async (stepContext) => {
      stepContext.logger.info(`Validating order ${orderId}`);
      return { orderId, status: "validated" };
    });

    // Step 2: Process payment
    const paymentResult = await context.step(async (stepContext) => {
      stepContext.logger.info(`Processing payment for order ${orderId}`);
      return { orderId, status: "paid", amount: 99.99 };
    });

    // Wait for 10 seconds to simulate external confirmation
    await context.wait({ seconds: 10 });

    // Step 3: Confirm order
    const confirmationResult = await context.step(async (stepContext) => {
      stepContext.logger.info(`Confirming order ${orderId}`);
      return { orderId, status: "confirmed" };
    });

    return {
      orderId: orderId,
      status: "completed",
      steps: [validationResult, paymentResult, confirmationResult]
    };
  }
);

배포(DEPLOY) 섹션에서 배포(Deploy)를 선택해서 함수의 코드를 업데이트합니다.

지속 함수 코드 이해하기 다음 단계로 넘어가기 전에 함수 코드를 살펴보고 지속 함수의 핵심 개념을 이해해 보세요.

withDurableExecution 래퍼:

지속 함수는 withDurableExecution로 감싸져 있어요. 이 래퍼는 DurableContext 객체를 제공하고 체크포인트 작업을 관리해서 지속 실행을 가능하게 해요.
DurableContext 객체:

표준 Lambda 컨텍스트 대신 함수는 DurableContext를 받아요. 이 객체는 체크포인트를 만드는 step()과 wait() 같은 지속 작업용 메서드를 제공해요.
단계와 체크포인트:

각 context.step() 호출은 실행 전후에 체크포인트를 만들어요. 함수가 중단되면 마지막으로 완료된 체크포인트부터 재개돼요. 함수는 완료된 단계를 다시 실행하지 않아요. 대신 저장된 결과를 사용해요.
대기 작업:

context.wait() 호출은 컴퓨팅 리소스를 소모하지 않고 실행을 일시 중지해요. 대기가 완료되면 Lambda가 함수를 다시 호출하고 체크포인트 로그를 리플레이하면서 완료된 단계에 저장된 값을 대체해요.
리플레이 메커니즘:

대기나 중단 후 함수가 재개되면 Lambda는 코드를 처음부터 실행해요. 하지만 완료된 단계는 다시 실행되지 않아요. Lambda는 체크포인트 로그에서 결과를 리플레이해요. 그래서 코드는 결정적이어야 해요.

Python

콘솔에서 코드를 수정하려면

코드(Code) 탭을 선택합니다.

콘솔의 기본 제공 코드 편집기에서 Lambda가 만든 함수 코드가 보일 거예요. 코드 편집기에 lambda_function.py 탭이 보이지 않으면 다음 다이어그램과 같이 파일 탐색기에서 lambda_function.py를 선택하세요.

다음 코드를 lambda_function.py 탭에 붙여넣어 Lambda가 만든 코드를 대체합니다.

from aws_durable_execution_sdk_python import (
    DurableContext,
    durable_execution,
    durable_step,
)
from aws_durable_execution_sdk_python.config import Duration

@durable_step
def validate_order(step_context, order_id):
    step_context.logger.info(f"Validating order {order_id}")
    return {"orderId": order_id, "status": "validated"}

@durable_step
def process_payment(step_context, order_id):
    step_context.logger.info(f"Processing payment for order {order_id}")
    return {"orderId": order_id, "status": "paid", "amount": 99.99}

@durable_step
def confirm_order(step_context, order_id):
    step_context.logger.info(f"Confirming order {order_id}")
    return {"orderId": order_id, "status": "confirmed"}

@durable_execution
def lambda_handler(event, context: DurableContext):
    order_id = event['orderId']

    # Step 1: Validate order
    validation_result = context.step(validate_order(order_id))

    # Step 2: Process payment
    payment_result = context.step(process_payment(order_id))

    # Wait for 10 seconds to simulate external confirmation
    context.wait(Duration.from_seconds(10))

    # Step 3: Confirm order
    confirmation_result = context.step(confirm_order(order_id))

    return {
        "orderId": order_id,
        "status": "completed",
        "steps": [validation_result, payment_result, confirmation_result]
    }

배포(DEPLOY) 섹션에서 배포(Deploy)를 선택해서 함수의 코드를 업데이트합니다.

지속 함수 코드 이해하기 다음 단계로 넘어가기 전에 함수 코드를 살펴보고 지속 함수의 핵심 개념을 이해해 보세요.

@durable_execution 데코레이터:

핸들러 함수는 @durable_execution으로 장식돼 있어요. 이 데코레이터는 DurableContext 객체를 제공하고 체크포인트 작업을 관리해서 지속 실행을 가능하게 해요.
@durable_step 데코레이터:

각 단계 함수는 @durable_step으로 장식돼 있어요. 이 데코레이터는 함수를 체크포인트를 만드는 지속 단계로 표시해요.
DurableContext 객체:

표준 Lambda 컨텍스트 대신 함수는 DurableContext를 받아요. 이 객체는 체크포인트를 만드는 step()과 wait() 같은 지속 작업용 메서드를 제공해요.
단계와 체크포인트:

각 context.step() 호출은 실행 전후에 체크포인트를 만들어요. 함수가 중단되면 마지막으로 완료된 체크포인트부터 재개돼요. 함수는 완료된 단계를 다시 실행하지 않아요. 대신 저장된 결과를 사용해요.
대기 작업:

context.wait() 호출은 컴퓨팅 리소스를 소모하지 않고 실행을 일시 중지해요. 대기가 완료되면 Lambda가 함수를 다시 호출하고 체크포인트 로그를 리플레이하면서 완료된 단계에 저장된 값을 대체해요.
Python SDK는 동기식이에요:

Python SDK는 await를 사용하지 않아요. 모든 지속 작업은 동기식 메서드 호출이에요.

콘솔 코드 편집기를 사용해서 지속 함수 호출하기

명시적 버전이 지정(또는 게시)되지 않으면 콘솔은 $LATEST 버전 한정자를 사용해서 지속 함수를 호출해요. 하지만 코드의 결정적 실행을 위해서는 항상 안정적인 버전을 가리키는 한정된 ARN을 사용해야 해요.

함수 버전을 게시하려면

버전(Versions) 탭을 선택합니다.
새 버전 게시(Publish new version)를 선택합니다.
버전 설명(Version description)에 Initial version을 입력합니다(선택 사항).
게시(Publish)를 선택합니다.
Lambda가 함수 버전 1을 만들어요. 이제 함수 ARN 끝에 :1이 포함되어 버전 1임을 나타내는 것을 확인하세요.

이제 함수에 보낼 테스트 이벤트를 만들어요. 이벤트는 주문 ID를 포함하는 JSON 형식 문서예요.

테스트 이벤트를 만들려면

콘솔 코드 편집기의 테스트 이벤트(TEST EVENTS) 섹션에서 테스트 이벤트 생성(Create test event)을 선택합니다.
이벤트 이름(Event Name)에 myTestEvent를 입력합니다.
이벤트 JSON(Event JSON) 섹션에서 기본 JSON을 다음으로 대체합니다.
```
{
  "orderId": "order-12345"
}
```
저장(Save)을 선택합니다.

지속 함수를 테스트하고 실행을 확인하려면

콘솔 코드 편집기의 테스트 이벤트(TEST EVENTS) 섹션에서 테스트 이벤트 옆의 실행 아이콘을 선택하세요.

지속 함수가 실행을 시작해요. 10초 대기가 포함되어 있으므로 초기 호출이 빠르게 완료되고 함수는 대기 기간 후에 재개돼요. 지속 실행(Durable executions) 탭에서 실행 진행 상황을 볼 수 있어요.

지속 함수 실행을 보려면

지속 실행(Durable executions) 탭을 선택합니다.
목록에서 실행을 찾습니다. 실행은 현재 상태(실행 중(Running), 성공(Succeeded), 실패(Failed))를 보여줘요.
실행 ID를 선택해서 다음을 포함한 세부 정보를 확인합니다.
- 각 단계가 완료된 시점을 보여주는 실행 타임라인
- 체크포인트 기록
- 대기 기간
- 단계 결과

CloudWatch Logs에서 함수 로그를 확인해 각 단계의 콘솔 출력을 볼 수도 있어요.

CloudWatch Logs에서 함수의 호출 기록을 보려면

CloudWatch 콘솔의 로그 그룹 페이지를 엽니다.
함수의 로그 그룹(/aws/lambda/myDurableFunction)을 선택합니다.
아래로 스크롤해서 확인하려는 함수 호출의 로그 스트림(Log stream)을 선택합니다.

초기 실행과 대기 후의 리플레이를 포함한 각 함수 호출에 대한 로그 항목이 보일 거예요.

참고 DurableContext의 로거(예: context.logger 또는 stepContext.logger)를 사용하면 Lambda 콘솔의 지속 실행 및 단계 보기에도 로그가 표시돼요. 이 로그가 로드되는 데 시간이 조금 걸릴 수 있어요.

정리하기

예시 지속 함수 작업이 끝나면 삭제하세요. 함수 로그를 저장하는 로그 그룹과 콘솔이 만든 실행 역할도 삭제할 수 있어요.

Lambda 함수를 삭제하려면

Lambda 콘솔의 함수 페이지를 엽니다.
만든 함수를 선택합니다.
작업(Actions), 삭제(Delete)를 선택합니다.
텍스트 입력 필드에 confirm을 입력하고 삭제(Delete)를 선택합니다.

로그 그룹을 삭제하려면

CloudWatch 콘솔의 로그 그룹 페이지를 엽니다.
함수의 로그 그룹(/aws/lambda/myDurableFunction)을 선택합니다.
작업(Actions), 로그 그룹 삭제(Delete log group(s))를 선택합니다.
로그 그룹 삭제(Delete log group(s)) 대화 상자에서 삭제(Delete)를 선택합니다.

실행 역할을 삭제하려면

AWS Identity and Access Management(IAM) 콘솔의 역할 페이지를 엽니다.
함수의 실행 역할(예: myDurableFunction-role-{{31exxmpl}})을 선택합니다.
삭제(Delete)를 선택합니다.
역할 삭제(Delete role) 대화 상자에 역할 이름을 입력하고 삭제(Delete)를 선택합니다.

추가 리소스 및 다음 단계

이제 콘솔을 사용해서 간단한 지속 함수를 만들고 테스트했으니 다음 단계를 진행해 보세요:

분산 트랜잭션, 주문 처리, 인간 검토 워크플로를 포함한 지속 함수의 일반적인 사용 사례에 대해 알아보세요. 예시를 참고하세요.
CloudWatch 지표와 실행 기록으로 지속 함수 실행을 모니터링하는 방법을 이해하세요. 모니터링 및 디버깅을 참고하세요.
지속 함수를 동기식·비동기식으로 호출하고 장기 실행을 관리하는 방법을 알아보세요. 지속 함수 호출을 참고하세요.
결정적 코드 작성, 체크포인트 크기 관리, 비용 최적화의 모범 사례를 따르세요. 모범 사례를 참고하세요.
로컬과 클라우드에서 지속 함수를 테스트하는 방법을 알아보세요. 지속 함수 테스트를 참고하세요.
지속 함수와 Step Functions를 비교해서 각 접근 방식이 언제 가장 효과적인지 이해하세요. 지속 함수 또는 Step Functions를 참고하세요.

더 알아보기 (Learn more)

이 주제는 Lambda 콘솔을 사용해서 지속 함수를 만들고 테스트하는 방법을 설명해요. 지속 함수의 개념과 사용 사례에 대한 자세한 내용은 Lambda 개발자 안내서의 지속 함수 관련 주제를 참고하세요.