스케줄러 결과 계약과 안전한 실패 관측
스케줄러 작업이 예외를 던지지 않았다는 사실은 성공을 뜻하지 않는다. 내부에서 오류를 잡고 None, error, 처리 수, partial을 반환하는 작업이 섞이면 관제는 정상·빈 결과·부분 실패를 구분하지 못한다.
목차
스케줄러 작업이 예외를 던지지 않았다는 사실은 성공을 뜻하지 않는다. 내부에서 오류를 잡고 None, error, 처리 수, partial을 반환하는 작업이 섞이면 관제는 정상·빈 결과·부분 실패를 구분하지 못한다.
실행 결과가 운영 판단이 되기까지
중복 실행 제한과 멱등 키로 처리 범위를 고정합니다.
완료·빈 결과·건너뜀·부분 실패·재시도·실패로 수렴합니다.
원문 대신 상태 코드와 실패 범위만 저장합니다.
상태와 retryable 값에 맞춰 종료·재개·운영자 확인을 선택합니다.
상태를 고정한다
작업 결과는 최소한 completed, empty, skipped, partial, retrying, failed 중 하나로 수렴한다. 처리 개수는 보조 지표이고, 상태가 완료인지가 먼저다. 예를 들어 12개 항목을 묶어 생성하는 배치는 일부만 생성되면 partial 또는 failed이며, 완전한 묶음만 skip한다.
실패 원문을 저장하지 않는다
외부 응답·URL·DSN·사용자 입력이 예외 문자열에 섞일 수 있다. 실패 테이블과 로그에는 status:partial, status:failed, exception:TimeoutError 같은 제한된 코드만 남기고, 원문은 반환 계약이나 사용자 응답으로 흘리지 않는다. 이 코드는 재시도 여부와 운영 화면의 필터에 충분하다.
상태 전이와 후속 행동
| 상태 | 의미 | 자동 재시도 | 운영자 행동 |
|---|---|---|---|
completed |
계약 범위 전체 완료 | 없음 | 표본 확인 |
empty |
정상 결과 0건 | 보통 없음 | 입력 기간 확인 |
skipped |
완전한 결과 존재 | 없음 | skip 근거 확인 |
partial |
일부만 반영 | 멱등성이 증명될 때만 | 누락 범위 재실행 |
retrying |
bounded backoff 중 | 상한 내 | 반복 원인 관찰 |
failed |
상한 또는 비재시도 오류 | 없음 | 원인 제거 후 재개 |
{"status":"partial","processed":9,"failed":3,"errorCode":"PROVIDER_TIMEOUT","retryable":true}
processed > 0만 보고 성공으로 바꾸면 누락이 영구화됩니다. 반대로 empty를 실패로 재시도하면 외부 API와 DB 쓰기 비용만 늘어납니다. 상태, 범위, 재시도 가능 여부를 분리해야 합니다.
완료 기준
- 예외·구조화 실패·부분 결과가 같은 scheduler failure 경로에 기록된다.
- 성공 수가 있어도 실패 범위가 있으면 성공으로만 관측되지 않는다.
- 실패 저장소가 내려가도 scheduler 자체는 다음 job을 계속 실행한다.
- 운영자는 job ID, 상태 코드, 재시도 범위를 조회할 수 있지만 민감한 원문은 볼 수 없다.