5.2 KiB
5.2 KiB
SDD: 작업 복구와 관측성
위치
- Milestone: Milestone 문서
- Phase: PHASE.md
상태
[초안]
SDD 잠금
- 상태: 잠금
- 사용자 리뷰: USER_REVIEW.md
- 잠금 항목:
- [D01] 자동 재시도·비용 보호와 최종 실패 작업 운영 정책을 확정한다.
문제 / 비목표
- 문제: 재시작·단절에서 작업을 복구하되 비용이 드는 분석·수정을 무한 또는 중복 실행하지 않아야 한다.
- 비목표:
- 별도 분산 큐 서비스
- 자동 병합
- 장기 분석 데이터 웨어하우스
Source of Truth
| 영역 | 기준 | 메모 |
|---|---|---|
| Roadmap | Milestone 문서 | 기능 범위와 완료 상태 |
| Code | internal/domain/remediation/, internal/platform/database/, internal/platform/logging/ |
작업 원장과 관측 신호 |
| External Provider | IOP 및 저장소 제공자 실행 상태 | 외부 상태는 재개 근거로만 소비 |
| User Decision | D01 | 재시도 한도, 비용, 보존과 수동 재실행 |
State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|---|---|---|---|
| 대기 | 실행 가능한 작업이 있음 | 임대됨 | 소유자·만료 시각 원자 갱신 |
| 임대됨 | 작업 실행 시작 | 실행중 | 실행 ID와 heartbeat |
| 실행중 | heartbeat가 유지됨 | 실행중 | 임대 갱신 |
| 실행중 | 일시 실패와 한도 여유 | 재시도 대기 | 실패 단계·시도 횟수·다음 시각 |
| 실행중 | 성공 또는 영구 실패 | 종료 | 최종 결과 또는 표준 실패 |
| 임대됨 또는 실행중 | 임대 만료 | 대기 또는 조사 필요 | 외부 실행의 모호성 판정 |
Interface Contract
- 계약 원문: 없음
- 입력:
- 작업 ID, 상태, 시도 횟수와 외부 실행 ID
- 실패 단계, 재시도 가능 여부와 D01 정책
- 출력:
- 임대 소유자, 다음 실행 시각과 최종 상태
- 상관관계 로그, 지표와 운영자 동작 감사 기록
- 금지:
- 모호한 수정 실행의 무조건 재시작
- 한도 없는 자동 재시도
- 감사 기록 없는 수동 재실행·취소
Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|---|---|---|---|---|
| S01 | claim-work |
여러 작업자가 같은 작업을 조회함 | 임대를 시도함 | 한 작업자만 유효 소유권을 얻음 |
| S02 | resume-work |
프로세스가 실행 중 종료됨 | 서버가 재시작됨 | 마지막 안전 상태와 이벤트 순서에서 재개됨 |
| S03 | retry-policy |
일시 또는 영구 실패가 발생함 | D01 정책을 평가함 | 허용된 단계·횟수·비용 안에서만 재시도됨 |
| S04 | manual-action |
권한 있는 운영자가 실패 작업을 선택함 | 재실행·취소함 | 멱등하게 반영되고 감사 기록이 남음 |
| S05 | correlation |
한 오류가 여러 단계로 진행됨 | 로그와 이력을 조회함 | 오류부터 외부 요청까지 같은 상관관계로 연결됨 |
| S06 | metrics-alerts |
지연·실패·정체가 발생함 | 지표를 수집함 | 단계별 상태와 경보 임계치를 관찰할 수 있음 |
| S07 | recovery-tests |
종료·임대 만료·IOP 단절을 주입함 | 복구를 수행함 | 중복 변경 없이 기대 상태로 수렴함 |
Evidence Map
| Scenario | Required Evidence | agent-task 연결 |
완료 Evidence 기대 |
|---|---|---|---|
| S01 | 동시 임대 경쟁 검사 | agent-task/m-workflow-recovery-observability/... |
claim-work 완료 근거 |
| S02 | 재시작 복구 통합 검사 | agent-task/m-workflow-recovery-observability/... |
resume-work 완료 근거 |
| S03 | 재시도 정책 표 검사 | agent-task/m-workflow-recovery-observability/... |
retry-policy 완료 근거 |
| S04 | 운영자 권한·감사 검사 | agent-task/m-workflow-recovery-observability/... |
manual-action 완료 근거 |
| S05 | 상관관계 로그 검색 결과 | agent-task/m-workflow-recovery-observability/... |
correlation 완료 근거 |
| S06 | 지표·경보 smoke | agent-task/m-workflow-recovery-observability/... |
metrics-alerts 완료 근거 |
| S07 | 장애 주입 최종 결과 | agent-task/m-workflow-recovery-observability/... |
recovery-tests 최종 검증 |
Cross-repo Dependencies
- IOP 실행 재개 기능을 소비하지만 특정 IOP Milestone 경로가 없어 workspace 잠금은 만들지 않는다.
Drift Check
- Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- Evidence Map이 code-review와
complete.log에서 검증 가능하다. - 외부 계약 원문을 SDD에 복제하지 않았다.
- 사용자 결정은 USER_REVIEW.md에 분리했다.
사용자 리뷰 이력
- [D01] 응답 대기
작업 컨텍스트
- 표준선: PostgreSQL 작업 원장과 임대를 사용하고, 외부 변경 결과가 모호하면 자동 재실행보다 조사 상태를 우선한다.
- 후속 SDD: 운영 배포 준비