86 lines
8.2 KiB
Markdown
86 lines
8.2 KiB
Markdown
---
|
|
title: "AWS Well-Architected Framework — REL05-BP03: Control and limit retry calls"
|
|
source_type: official-doc
|
|
url: https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html
|
|
archive_url:
|
|
related_branches: [feature-background-job-async-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, error-handling, aws, exponential-backoff, jitter, retry-policy, dead-letter-queue]
|
|
created: 2026-06-11
|
|
---
|
|
|
|
# AWS Well-Architected Framework — REL05-BP03: Control and limit retry calls
|
|
|
|
> Layer: `raw/official-docs/` — AWS Well-Architected Framework Reliability Pillar 공식 문서 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-background-job-async-contract]] | D4 — "limit the maximum number of retries" 공식 근거 + non-transient error 는 retry 없이 즉시 fail(DLQ) 조건 + anti-pattern (non-idempotent retry / multi-layer retry storm) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html
|
|
- 아카이브 URL: (미등록)
|
|
- 저자 / 조직: Amazon Web Services (AWS Well-Architected Team)
|
|
- 발행일: (공식 문서 — 지속 관리 페이지, 특정 발행일 없음)
|
|
- 마지막 확인일: 2026-06-11
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-background-job-async-contract` branch 의 D4 결정(기본 backoff = exponential + jitter, max attempts 제한, DLQ after exhausted)이 `UNSUPPORTED_DECISION` 상태였다. 본 AWS Well-Architected REL05-BP03 공식 문서가 "limit the maximum number of retries", non-transient error retry 금지, multi-layer retry storm anti-pattern 을 직접 권고하므로 D4 의 정량 방향성과 금지 조건의 외부 근거로 보관한다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Opening summary] "Use exponential backoff to retry requests at progressively longer intervals between each retry. Introduce jitter between retries to randomize retry intervals. Limit the maximum number of retries."
|
|
|
|
> [§Benefits] "Finally, it's important to configure a maximum number of retries or elapsed time to avoid creating backlogs that produce metastable failures."
|
|
|
|
> [§Common anti-patterns] "Failing to understand published error codes from dependencies, leading to retrying all errors, including those with a clear cause that indicates lack of permission, configuration error, or another condition that predictably will not resolve without manual intervention."
|
|
|
|
> [§Common anti-patterns] "Retrying at multiple layers of your application stack in a manner which compounds retry attempts further consuming resources in a retry storm. Be sure to understand how these errors affect your application the dependencies you rely on, then implement retries at only one level."
|
|
|
|
> [§Common anti-patterns] "Retrying service calls that are not idempotent, causing unexpected side effects like duplicated results."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| WAF-REL05-C1 | Retry 는 exponential backoff + jitter + maximum retry 제한 을 반드시 함께 구현해야 한다 | [§Opening] "Use exponential backoff to retry requests at progressively longer intervals between each retry. Introduce jitter between retries to randomize retry intervals. Limit the maximum number of retries." | `official-vendor-doc` | 분산 시스템의 모든 클라이언트 retry 구현 | 최대 retry 횟수의 정확한 정량값(예: 3회)을 직접 지정하지 않음 |
|
|
| WAF-REL05-C2 | Maximum retry 횟수 또는 elapsed time 을 설정하지 않으면 backlog 가 누적되어 metastable failure 를 유발한다 | [§Benefits] "it's important to configure a maximum number of retries or elapsed time to avoid creating backlogs that produce metastable failures." | `official-vendor-doc` | retry 있는 모든 클라이언트 코드 | 특정 숫자(3, 5 등) 또는 특정 elapsed time 값을 권고하지 않음 |
|
|
| WAF-REL05-C3 | Manual intervention 이 필요한 non-transient error(permission 오류, configuration 오류 등)는 retry 해서는 안 된다 | [§Common anti-patterns] "another condition that predictably will not resolve without manual intervention." | `official-vendor-doc` | 모든 retry 구현의 error 분류 로직 | 어떤 HTTP status code 를 non-transient 로 분류할지 직접 목록화하지 않음 |
|
|
| WAF-REL05-C4 | Application stack 의 여러 레이어에서 중첩 retry 는 retry storm 을 유발하며 단일 레이어에서만 구현해야 한다 | [§Common anti-patterns] "Retrying at multiple layers of your application stack in a manner which compounds retry attempts further consuming resources in a retry storm. Be sure to understand how these errors affect your application the dependencies you rely on, then implement retries at only one level." | `official-vendor-doc` | multi-tier 아키텍처 (예: HTTP client + scheduler + outbox publisher 가 모두 retry 하는 경우) | 단일 레이어 위치(service layer vs infrastructure layer)의 선택 기준을 명시하지 않음 |
|
|
| WAF-REL05-C5 | Idempotent 하지 않은 서비스 호출에 retry 를 적용하면 중복 결과 등 예상치 못한 부작용이 발생한다 | [§Common anti-patterns] "Retrying service calls that are not idempotent, causing unexpected side effects like duplicated results." | `official-vendor-doc` | retry 구현 전 idempotency 검증이 필요한 모든 서비스 호출 | idempotency 구현 방법(idempotency key, conditional write 등)을 직접 설명하지 않음 (REL04-BP04 참조) |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `WAF-REL05-C1`: exponential backoff + jitter + max retry limit 의 세 요소가 함께 필요함
|
|
- `WAF-REL05-C2`: max retry 또는 elapsed time 설정 없음 = metastable failure 위험 (Risk: High)
|
|
- `WAF-REL05-C3`: non-transient error(manual intervention 필요) → retry 금지
|
|
- `WAF-REL05-C4`: multi-layer retry 중첩 = retry storm anti-pattern → 단일 레이어 구현
|
|
- `WAF-REL05-C5`: non-idempotent 호출에 retry = 중복 부작용 anti-pattern
|
|
- 이 자료가 증명하지 않는 것:
|
|
- max retry 정확한 정량값(3회, 5회 등). 정량값은 use-case 별 측정 필요 (`WAF-REL05-C1`, `WAF-REL05-C2` 공통)
|
|
- DLQ(Dead Letter Queue) 아키텍처 자체의 설계 방법 — DLQ 를 "retry 소진 후 격리"로 사용하는 것은 이 문서의 scope 밖
|
|
- 어떤 HTTP status code 가 "predictably will not resolve" 에 해당하는지 목록화되지 않음 (`WAF-REL05-C3`)
|
|
- retry 위치(service layer vs infrastructure layer 중 어디)를 명시하지 않음 (`WAF-REL05-C4`)
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl background job 의 max=3 결정은 이 문서로 "max limit 필요" 방향을 정당화할 수 있으나 "3이 옳다"는 별도 측정 필요 (`WAF-REL05-C2`)
|
|
- outbox publisher + background job executor 가 각각 retry 하는 경우 `WAF-REL05-C4` 위반 여부 검토 — 단일 retry 레이어 지정 필요
|
|
|
|
## 메모 / Notes
|
|
|
|
- Risk level = **High** (원문 명시): "Level of risk exposed if this best practice is not established: High"
|
|
- AWS Builder's Library 의 "Timeouts, retries, and backoff with jitter" 가 이 문서와 연계됨 — 더 상세한 구현 guidance 포함. 후속 raw 추가 권고.
|
|
- REL05-BP04 (Fail fast and limit queues) 및 REL04-BP04 (Make mutating operations idempotent) 가 `WAF-REL05-C3`, `WAF-REL05-C5` 와 직접 연계. 관련 페이지 raw 추가 시 Claim cross-reference 가능.
|
|
- Spring Retry 및 Resilience4j Retry 가 Related examples 로 링크됨 — ca-tmpl 의 구체 구현체 선택 시 참조.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: [[raw/official-docs/outbound-resilience4j-vs-spring-retry]] (존재 시)
|
|
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/retry-backoff-pattern]]` (생성 시)
|
|
- AWS Builder's Library retry/backoff 상세: https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ (raw 추가 권고)
|