지속 함수 모니터링

CloudWatch 지표, CloudWatch Logs, 추적(tracing)으로 지속 함수를 모니터링할 수 있습니다. 지속 함수는 장기간 실행되고 여러 함수 호출에 걸칠 수 있으므로, 이를 모니터링하려면 체크포인트, 상태 전환, 재생 동작을 포함한 고유한 실행 패턴을 이해해야 합니다.

출처: AWS Lambda 개발자 안내서

본문

지속 함수에 적용되는 할당량에 대한 자세한 내용은 '지속 함수 할당량'을 참고하세요.

CloudWatch 지표

Lambda는 추가 비용 없이 CloudWatch에 지표를 자동으로 게시합니다. 지속 함수는 표준 Lambda 지표 외에도 장기 실행 워크플로, 상태 관리, 리소스 활용을 모니터링하는 데 도움이 되는 추가 지표를 제공합니다.

지속 실행 지표

Lambda는 지속 실행에 대해 다음 지표를 내보냅니다.

지표	설명
ApproximateRunningDurableExecutions	RUNNING 상태의 지속 실행 수
ApproximateRunningDurableExecutionsUtilization	계정의 최대 실행 중 지속 실행 할당량 중 현재 사용 중인 백분율
DurableExecutionDuration	지속 실행이 RUNNING 상태로 머문 경과 벽시계 시간(밀리초)
DurableExecutionStarted	시작된 지속 실행 수
DurableExecutionStopped	StopDurableExecution API로 중지된 지속 실행 수
DurableExecutionSucceeded	성공적으로 완료된 지속 실행 수
DurableExecutionFailed	실패로 완료된 지속 실행 수
DurableExecutionTimedOut	구성된 실행 타임아웃을 초과한 지속 실행 수
DurableExecutionOperations	지속 실행 내에서 수행된 누적 작업 수(최대: 3,000)
DurableExecutionStorageWrittenBytes	지속 실행이 유지한 누적 데이터 양(바이트, 최대: 100 MB)

CloudWatch 지표

Lambda는 지속 함수에 대해 표준 호출, 성능, 동시성 지표를 내보냅니다. 지속 실행은 체크포인트와 재생을 진행하면서 여러 함수 호출에 걸칠 수 있으므로 이 지표들은 표준 함수와 다르게 동작합니다.

Invocations: 재생을 포함한 각 함수 호출을 셉니다. 단일 지속 실행이 여러 호출 데이터 포인트를 생성할 수 있습니다.
Duration: 각 함수 호출을 별도로 측정합니다. 단일 지속 실행이 걸린 총 시간에는 DurableExecutionDuration을 사용하세요.
Errors: 함수 호출 실패를 추적합니다. 실행 수준 실패에는 DurableExecutionFailed를 사용하세요.

표준 Lambda 지표 전체 목록은 'Lambda 함수의 지표 유형'을 참고하세요.

CloudWatch 경보 만들기

지표가 임계값을 초과할 때 알려주는 CloudWatch 경보를 만드세요. 일반적인 경보는 다음과 같습니다.

ApproximateRunningDurableExecutionsUtilization이 할당량의 80%를 초과
DurableExecutionFailed가 임계값 이상으로 증가
DurableExecutionTimedOut이 실행 타임아웃을 나타냄
DurableExecutionStorageWrittenBytes가 저장 한도에 가까워짐

자세한 내용은 'CloudWatch 경보 사용'을 참고하세요.

EventBridge 이벤트

Lambda는 지속 실행 상태 변경 이벤트를 EventBridge에 게시합니다. 이 이벤트를 사용해 워크플로를 트리거하고, 알림을 보내고, 지속 함수 전반의 실행 수명주기 변경을 추적할 수 있습니다.

지속 실행 상태 변경 이벤트

Lambda는 지속 실행이 상태를 변경할 때마다 EventBridge에 이벤트를 내보냅니다. 이 이벤트들은 다음 특성을 가집니다.

Source: aws.lambda
Detail type: Durable Execution Status Change

상태 변경 이벤트는 다음 실행 상태에 대해 게시됩니다.

RUNNING – 실행 시작
SUCCEEDED – 실행 성공적 완료
STOPPED – StopDurableExecution API로 실행 중지
FAILED – 실행이 오류로 실패
TIMED_OUT – 실행이 구성된 타임아웃을 초과

다음 예제는 지속 실행 상태 변경 이벤트를 보여줍니다.

{
  "version": "0",
  "id": "d019b03c-a8a3-9d58-85de-241e96206538",
  "detail-type": "Durable Execution Status Change",
  "source": "aws.lambda",
  "account": "123456789012",
  "time": "2025-11-20T13:08:22Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "durableExecutionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST/durable-execution/090c4189-b18b-4296-9d0c-cfd01dc3a122/9f7d84c9-ea3d-3ffc-b3e5-5ec51c34ffc9",
    "durableExecutionName": "order-123",
    "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function:2",
    "status": "RUNNING",
    "startTimestamp": "2025-11-20T13:08:22.345Z"
  }
}

종료 상태(SUCCEEDED, STOPPED, FAILED, TIMED_OUT)의 경우 이벤트에는 실행이 완료된 시점을 나타내는 endTimestamp 필드가 포함됩니다.

EventBridge 규칙 만들기

지속 실행 상태 변경 이벤트를 Amazon Simple Notification Service, Amazon Simple Queue Service, 다른 Lambda 함수 같은 대상으로 라우팅하는 EventBridge 규칙을 만드세요.

다음 예제는 모든 지속 실행 상태 변경과 일치하는 규칙을 만듭니다.

{
  "source": ["aws.lambda"],
  "detail-type": ["Durable Execution Status Change"]
}

다음 예제는 실패한 실행만 일치하는 규칙을 만듭니다.

{
  "source": ["aws.lambda"],
  "detail-type": ["Durable Execution Status Change"],
  "detail": {
    "status": ["FAILED"]
  }
}

다음 예제는 특정 함수의 상태 변경과 일치하는 규칙을 만듭니다.

{
  "source": ["aws.lambda"],
  "detail-type": ["Durable Execution Status Change"],
  "detail": {
    "functionArn": [{
      "prefix": "arn:aws:lambda:us-east-1:123456789012:function:my-function"
    }]
  }
}

EventBridge 규칙 만들기에 대한 자세한 내용은 EventBridge User Guide의 'Amazon EventBridge tutorials'를 참고하세요.

EventBridge 이벤트로 데드레터 큐 사용

EventBridge 상태 변경 이벤트는 지속 실행이 FAILED, STOPPED, TIMED_OUT 상태에 들어갈 때 실시간 알림을 제공하지만, 실행을 트리거한 원래 이벤트 페이로드는 포함하지 않습니다. 나중에 분석하거나 재처리하기 위해 트리거 이벤트를 캡처하려면 지속 함수에 데드레터 큐(DLQ)를 구성하세요.

비동기 호출 후 지속 실행이 실패하면 Lambda는 원래 트리거 이벤트를 구성된 DLQ로 보냅니다. 포괄적인 실패 처리 전략을 위해 EventBridge 이벤트와 DLQ를 함께 사용하세요.

EventBridge 이벤트 – 실행이 실패할 때 즉시 알림을 트리거하고, 대시보드를 갱신하고, 수정 워크플로를 시작합니다.
데드레터 큐 – 원래 이벤트 페이로드를 보존해 무엇이 실패를 일으켰는지 검사하고, 문제를 디버깅하고, 선택적으로 근본 문제를 고친 뒤 이벤트를 재처리할 수 있게 합니다.

함수에 DLQ를 구성하는 방법은 '데드레터 큐'를 참고하세요.

AWS X-Ray 추적

지속 함수에서 X-Ray 추적을 활성화할 수 있습니다. Lambda는 X-Ray 추적 헤더를 지속 실행에 전달하므로 워크플로 전반에 걸쳐 요청을 추적할 수 있습니다.

Lambda 콘솔로 X-Ray 추적을 활성화하려면 함수를 선택한 뒤 Configuration, Monitoring and operations tools를 선택하고 X-Ray 아래에서 Active tracing을 켜세요.

AWS CLI로 X-Ray 추적을 활성화하려면:

aws lambda update-function-configuration \
    --function-name my-durable-function \
    --tracing-config Mode=Active

AWS SAM으로 AWS X-Ray 추적을 활성화하려면:

Resources:
  MyDurableFunction:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      DurableConfig:
        ExecutionTimeout: 3600

X-Ray에 대한 자세한 내용은 AWS X-Ray Developer Guide를 참고하세요.

지속 함수 모니터링