Lambda 비동기 호출 레코드 캡처하기

Lambda는 비동기 호출의 레코드를 다음 AWS 서비스 중 하나로 보낼 수 있어요.

Amazon SQS – 표준 SQS 큐
Amazon SNS – 표준 SNS 주제
Amazon S3 – Amazon S3 버킷(실패 시에만)
AWS Lambda – Lambda 함수
Amazon EventBridge – EventBridge 이벤트 버스

호출 레코드에는 요청과 응답에 대한 세부 정보가 JSON 형식으로 포함돼요. 성공적으로 처리된 이벤트와 모든 처리 시도에 실패한 이벤트에 대해 별도의 대상을 구성할 수 있어요. 또는 버려진 이벤트를 위한 데드 레터 큐로 표준 Amazon SQS 큐나 표준 Amazon SNS 주제를 구성할 수도 있어요. 데드 레터 큐의 경우 Lambda는 응답에 대한 세부 정보 없이 이벤트 내용만 보내요.

Lambda가 구성한 대상으로 레코드를 보낼 수 없으면 DestinationDeliveryFailures 지표를 Amazon CloudWatch로 보내요. 구성에 지원되지 않는 대상 유형(예: Amazon SQS FIFO 큐, Amazon SNS FIFO 주제)이 포함된 경우 이런 일이 발생할 수 있어요. 권한 오류와 크기 제한으로 인해 전달 오류도 발생할 수 있어요. Lambda 호출 지표에 대한 자세한 내용은 호출 지표를 참고하세요.

참고 함수가 트리거되지 않도록 함수의 예약 동시성을 0으로 설정할 수 있어요. 비동기 호출된 함수의 예약 동시성을 0으로 설정하면 Lambda는 재시도 없이 새 이벤트를 구성된 데드 레터 큐나 실패 시 이벤트 대상으로 보내기 시작해요. 예약 동시성이 0으로 설정된 동안 전송된 이벤트를 처리하려면 데드 레터 큐나 실패 시 이벤트 대상에서 이벤트를 소비해야 해요.

출처: AWS Lambda 개발자 안내서

본문

대상 추가하기

비동기 호출의 레코드를 유지하려면 함수에 대상을 추가하세요. 성공하거나 실패한 호출을 대상으로 보내도록 선택할 수 있어요. 각 함수는 여러 대상을 가질 수 있으므로 성공 및 실패 이벤트에 대해 별도의 대상을 구성할 수 있어요. 대상으로 보내지는 각 레코드는 호출에 대한 세부 정보를 담은 JSON 문서예요. 오류 처리 설정과 마찬가지로 함수, 함수 버전, 별칭에 대상을 구성할 수 있어요.

팁 다음 이벤트 소스 매핑 유형에 대해서도 실패한 호출의 레코드를 유지할 수 있어요: Amazon Kinesis, Amazon DynamoDB, Apache Kafka(Amazon MSK 및 자체 관리형 Apache Kafka).

다음 표는 비동기 호출 레코드에 대해 지원되는 대상을 나열해요. Lambda가 선택한 대상으로 레코드를 성공적으로 보내려면 함수의 실행 역할에 관련 권한도 포함되어 있는지 확인하세요. 표는 각 대상 유형이 JSON 호출 레코드를 어떻게 수신하는지도 설명해요.

대상 유형	필요한 권한	대상별 JSON 형식
Amazon SQS 큐	sqs:SendMessage	Lambda는 호출 레코드를 `Message`로 대상에 전달해요.
Amazon SNS 주제	sns:Publish	Lambda는 호출 레코드를 `Message`로 대상에 전달해요.
Amazon S3 버킷(실패 시에만)	s3:PutObject s3:ListBucket	+ Lambda는 호출 레코드를 대상 버킷에 JSON 객체로 저장해요. + S3 객체 이름은 다음 명명 규칙을 사용해요: aws/lambda/async//YYYY/MM/DD/YYYY-MM-DDTHH.MM.SS-
Lambda 함수	lambda:InvokeFunction	Lambda는 호출 레코드를 페이로드로 함수에 전달해요.
EventBridge	events:PutEvents	+ Lambda는 호출 레코드를 PutEvents 호출의 `detail`로 전달해요. + `source` 이벤트 필드의 값은 `lambda`예요. + `detail-type` 이벤트 필드의 값은 "Lambda Function Invocation Result - Success" 또는 "Lambda Function Invocation Result - Failure"예요. + `resource` 이벤트 필드에는 함수와 대상 Amazon 리소스 이름(ARN)이 포함돼요. + 다른 이벤트 필드는 Amazon EventBridge 이벤트를 참고하세요.

참고 Amazon S3 대상의 경우 KMS 키를 사용해 버킷에서 암호화를 활성화했다면 함수에도 kms:GenerateDataKey 권한이 필요해요.

중요 대상으로 Amazon SNS를 사용할 때 Amazon SNS에는 최대 메시지 크기 제한 256KB가 있어요. 비동기 호출 페이로드가 1MB에 가까워지면 호출 레코드(원본 페이로드와 추가 메타데이터 포함)가 Amazon SNS 제한을 초과해서 전달 실패를 일으킬 수 있어요. 더 큰 페이로드에는 Amazon SQS 또는 Amazon S3 대상을 사용하는 것을 고려하세요.

다음 단계는 Lambda 콘솔과 AWS CLI를 사용해서 함수에 대한 대상을 구성하는 방법을 설명해요.

콘솔

Lambda 콘솔의 함수 페이지를 엽니다.
함수를 선택합니다.
함수 개요(Function overview)에서 대상 추가(Add destination)를 선택합니다.
소스(Source)에서 비동기 호출(Asynchronous invocation)을 선택합니다.
조건(Condition)에서 다음 옵션 중 하나를 선택합니다.
- 실패 시(On failure) – 이벤트가 모든 처리 시도를 실패하거나 최대 수명을 초과하면 레코드를 보냅니다.
- 성공 시(On success) – 함수가 비동기 호출을 성공적으로 처리하면 레코드를 보냅니다.
대상 유형(Destination type)에서 호출 레코드를 수신하는 리소스 유형을 선택합니다.
대상(Destination)에서 리소스를 선택합니다.
저장(Save)을 선택합니다.

AWS CLI

AWS CLI를 사용해서 대상을 구성하려면 update-function-event-invoke-config 명령을 실행하세요. 다음 예시는 이벤트를 처리할 수 없을 때 Lambda가 destination이라는 표준 SQS 큐로 레코드를 보내도록 구성해요.

aws lambda update-function-event-invoke-config \
  --function-name my-function \
  --destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-1:123456789012:{{destination}}"}'

Amazon S3 대상에 대한 보안 모범 사례

함수 구성에서 대상을 제거하지 않고 대상으로 구성된 S3 버킷을 삭제하면 보안 위험이 생길 수 있어요. 다른 사용자가 대상 버킷의 이름을 알게 되면 자신의 AWS 계정에 버킷을 다시 만들 수 있어요. 실패한 호출의 레코드가 해당 사용자의 버킷으로 전송되어 함수의 데이터가 노출될 수 있어요.

경고 함수의 호출 레코드가 다른 AWS 계정의 S3 버킷으로 전송되지 않도록 하려면 함수의 실행 역할에 s3:PutObject 권한을 계정의 버킷으로 제한하는 조건을 추가하세요.

다음 예시는 함수의 s3:PutObject 권한을 계정의 버킷으로 제한하는 IAM 정책을 보여줘요. 이 정책은 또한 Lambda가 S3 버킷을 대상으로 사용하는 데 필요한 s3:ListBucket 권한도 부여해요.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3BucketResourceAccountWrite",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::*/*",
                "arn:aws:s3:::*"
            ],
            "Condition": {
                "StringEquals": {
                    "s3:ResourceAccount": {{"111122223333"}}
                }
            }
        }
    ]
}

AWS Management Console 또는 AWS CLI를 사용해서 함수 실행 역할에 권한 정책을 추가하려면 다음 절차의 지침을 참고하세요.

콘솔

함수의 실행 역할에 권한 정책을 추가하려면(콘솔)

Lambda 콘솔의 함수 페이지를 엽니다.
실행 역할을 수정할 Lambda 함수를 선택합니다.
구성(Configuration) 탭에서 권한(Permissions)을 선택합니다.
실행 역할(Execution role) 탭에서 함수의 역할 이름(Role name)을 선택해서 역할의 IAM 콘솔 페이지를 엽니다.
다음을 수행해서 역할에 권한 정책을 추가합니다.
1. 권한 정책(Permissions policies) 창에서 권한 추가(Add permissions)를 선택하고 인라인 정책 생성(Create inline policy)을 선택합니다.
2. 정책 편집기(Policy editor)에서 JSON을 선택합니다.
3. 추가할 정책을 편집기에 붙여넣고(기존 JSON 대체)다음(Next)을 선택합니다.
4. 정책 세부 정보(Policy details)에서 정책 이름(Policy name)을 입력합니다.
5. 정책 생성(Create policy)을 선택합니다.

AWS CLI

함수의 실행 역할에 권한 정책을 추가하려면(CLI)

필요한 권한이 있는 JSON 정책 문서를 만들고 로컬 디렉터리에 저장합니다.
IAM put-role-policy CLI 명령을 사용해서 함수 실행 역할에 권한을 추가합니다. JSON 정책 문서를 저장한 디렉터리에서 다음 명령을 실행하고 역할 이름, 정책 이름, 정책 문서를 자신의 값으로 교체합니다.
```
aws iam put-role-policy \
--role-name {{my_lambda_role}} \
--policy-name LambdaS3DestinationPolicy \
--policy-document file://{{my_policy.json}}
```

예시 호출 레코드

호출이 조건과 일치하면 Lambda는 호출에 대한 세부 정보가 담긴 JSON 문서를 대상으로 보내요. 다음 예시는 함수 오류로 인해 세 번의 처리 시도가 실패한 이벤트에 대한 호출 레코드를 보여줘요.

예시

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

호출 레코드에는 이벤트, 응답, 레코드가 전송된 이유에 대한 세부 정보가 포함돼요.

대상으로의 요청 추적

AWS X-Ray를 사용해서 각 요청이 큐에 들어가고, Lambda 함수로 처리되고, 대상 서비스로 전달되는 연결된 보기를 볼 수 있어요. 함수나 함수를 호출하는 서비스에 대해 X-Ray 추적을 활성화하면 Lambda가 요청에 X-Ray 헤더를 추가하고 대상 서비스에 헤더를 전달해요. 업스트림 서비스의 트레이스는 다운스트림 Lambda 함수와 대상 서비스의 트레이스에 자동으로 연결되어 전체 애플리케이션의 종단 간 보기를 만들어요. 추적에 대한 자세한 내용은 AWS X-Ray를 사용한 Lambda 함수 호출 시각화를 참고하세요.

데드 레터 큐 추가하기

실패 시 대상의 대안으로 버려진 이벤트를 추가 처리하기 위해 함수에 데드 레터 큐를 구성할 수 있어요. 데드 레터 큐는 이벤트가 모든 처리 시도를 실패하거나 처리되지 않고 만료될 때 사용된다는 점에서 실패 시 대상과 동일하게 작동해요. 하지만 데드 레터 큐는 함수 수준에서만 추가·제거할 수 있어요. 함수 버전은 게시되지 않은 버전($LATEST)과 동일한 데드 레터 큐 설정을 사용해요. 실패 시 대상은 추가 대상을 지원하고 호출 레코드에 함수 응답에 대한 세부 정보를 포함해요.

데드 레터 큐의 이벤트를 재처리하려면 이를 Lambda 함수의 이벤트 소스로 설정할 수 있어요. 또는 이벤트를 수동으로 검색할 수도 있어요.

데드 레터 큐에는 Amazon SQS 표준 큐나 Amazon SNS 표준 주제를 선택할 수 있어요. FIFO 큐와 Amazon SNS FIFO 주제는 지원되지 않아요.

Amazon SQS 큐 – 큐는 실패한 이벤트를 검색할 때까지 보관해요. Lambda 함수나 CloudWatch 경보 같은 단일 엔터티가 실패한 이벤트를 처리할 것으로 예상된다면 Amazon SQS 표준 큐를 선택하세요. 자세한 내용은 Amazon SQS와 함께 Lambda 사용을 참고하세요.
Amazon SNS 주제 – 주제는 실패한 이벤트를 하나 이상의 대상으로 중계해요. 여러 엔터티가 실패한 이벤트에 대해 작업할 것으로 예상된다면 Amazon SNS 표준 주제를 선택하세요. 예를 들어 이메일 주소, Lambda 함수, HTTP 엔드포인트로 이벤트를 보내도록 주제를 구성할 수 있어요. 자세한 내용은 Amazon SNS 알림으로 Lambda 함수 호출을 참고하세요.

이벤트를 큐나 주제로 보내려면 함수에 추가 권한이 필요해요. 필요한 권한이 있는 정책을 함수의 실행 역할에 추가하세요. 대상 큐나 주제가 고객 관리형 AWS KMS 키로 암호화된 경우 함수 실행 역할과 키의 리소스 기반 정책 모두에 관련 권한이 포함되어 있는지 확인하세요.

대상을 만들고 함수 실행 역할을 업데이트한 후 함수에 데드 레터 큐를 추가하세요. 여러 함수가 동일한 대상으로 이벤트를 보내도록 구성할 수 있어요.

콘솔

Lambda 콘솔의 함수 페이지를 엽니다.
함수를 선택합니다.
구성(Configuration)을 선택한 다음 비동기 호출(Asynchronous invocation)을 선택합니다.
비동기 호출(Asynchronous invocation)에서 편집(Edit)을 선택합니다.
데드 레터 큐 서비스(Dead-letter queue service)를 Amazon SQS 또는 Amazon SNS로 설정합니다.
대상 큐나 주제를 선택합니다.
저장(Save)을 선택합니다.

AWS CLI

AWS CLI로 데드 레터 큐를 구성하려면 update-function-configuration 명령을 사용하세요.

aws lambda update-function-configuration \
  --function-name my-function \
  --dead-letter-config TargetArn={{arn:aws:sns:us-east-1:123456789012:my-topic}}

Lambda는 이벤트를 속성의 추가 정보와 함께 그대로 데드 레터 큐로 보내요. 이 정보를 사용해서 함수가 반환한 오류를 식별하거나 이벤트를 로그 또는 AWS X-Ray 트레이스와 연관시킬 수 있어요.

데드 레터 큐 메시지 속성

RequestID(String) – 호출 요청의 ID입니다. 요청 ID는 함수 로그에 표시됩니다. X-Ray SDK를 사용해서 트레이스의 속성에 요청 ID를 기록할 수도 있습니다. 그런 다음 X-Ray 콘솔에서 요청 ID로 트레이스를 검색할 수 있습니다.
ErrorCode(Number) – HTTP 상태 코드입니다.
ErrorMessage(String) – 오류 메시지의 처음 1KB입니다.

Lambda가 데드 레터 큐로 메시지를 보낼 수 없으면 이벤트를 삭제하고 DeadLetterErrors 지표를 내보내요. 이는 권한 부족이나 메시지의 총 크기가 대상 큐나 주제의 제한을 초과하기 때문에 발생할 수 있어요. 예를 들어 본문 크기가 1MB에 가까운 Amazon SNS 알림이 오류를 일으키는 함수를 트리거한다고 가정해 보세요. 이 경우 Amazon SNS가 추가하는 이벤트 데이터와 Lambda가 추가하는 속성이 결합되어 메시지가 데드 레터 큐에서 허용되는 최대 크기를 초과할 수 있어요.

Amazon SQS를 이벤트 소스로 사용한다면 Lambda 함수가 아니라 Amazon SQS 큐 자체에 데드 레터 큐를 구성하세요. 자세한 내용은 Amazon SQS와 함께 Lambda 사용을 참고하세요.

더 알아보기 (Learn more)

이 주제는 비동기 호출 레코드를 캡처하는 방법을 설명해요. 비동기 호출과 오류 처리에 대한 자세한 내용은 Lambda 개발자 안내서의 관련 주제를 참고하세요.