You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
192 lines
4.5 KiB
Markdown
192 lines
4.5 KiB
Markdown
# Phase 2 운영 Runbook
|
|
|
|
## 1. 목적
|
|
|
|
이 문서는 운영자가 Phase 2 수집 파이프라인을 실행, 점검, 재시도, 복구할 때 따르는 절차를 정의합니다.
|
|
|
|
## 2. 일일 운영 루틴
|
|
|
|
### 장 전 / 오전
|
|
|
|
- SEC submissions poll 정상 동작 여부 확인
|
|
- 전일 FINRA 파일 수집 완료 여부 확인
|
|
- FRED 최신 observation lag 확인
|
|
- source freeze 설정이 의도치 않게 켜져 있지 않은지 확인
|
|
|
|
### 장 후
|
|
|
|
- Alpaca daily bars 적재 완료 여부 확인
|
|
- SEC 신규 filing 유입량 점검
|
|
- 실패 잡 및 quarantine 건수 확인
|
|
- 데이터 품질 검증 리포트 확인
|
|
|
|
## 3. 기본 확인 명령
|
|
|
|
예시 명령은 프로젝트 CLI 이름에 맞게 조정합니다.
|
|
|
|
```bash
|
|
python -m apps.ops.show_recent_runs --limit 20
|
|
python -m apps.ops.show_failed_runs --since 24h
|
|
python -m apps.ops.show_checkpoints
|
|
python -m apps.ops.show_quarantine --since 7d
|
|
```
|
|
|
|
## 4. 특정 source 수동 실행
|
|
|
|
### SEC poll
|
|
|
|
```bash
|
|
python -m apps.collector.sec_collector.main --mode poll --run-id MANUAL_SEC_POLL_001
|
|
```
|
|
|
|
### Alpaca daily backfill
|
|
|
|
```bash
|
|
python -m apps.collector.alpaca_collector.main \
|
|
--mode backfill \
|
|
--symbols AAPL,MSFT,NVDA \
|
|
--start-date 2026-01-01 \
|
|
--end-date 2026-01-31
|
|
```
|
|
|
|
### FRED sync
|
|
|
|
```bash
|
|
python -m apps.collector.fred_collector.main --mode poll
|
|
```
|
|
|
|
### FINRA fetch
|
|
|
|
```bash
|
|
python -m apps.collector.finra_collector.main --mode poll
|
|
```
|
|
|
|
## 5. 실패 시 대응 절차
|
|
|
|
### 5.1 단일 run 실패
|
|
|
|
1. `job_runs`에서 상태와 오류 유형 확인
|
|
2. raw 파일이 쓰였는지 확인
|
|
3. checkpoint가 잘못 전진했는지 확인
|
|
4. retriable 이면 동일 파라미터로 재시도
|
|
5. terminal 이면 source payload와 schema drift 여부 확인
|
|
|
|
### 5.2 같은 잡이 연속 실패
|
|
|
|
1. source freeze 여부 확인
|
|
2. 환경변수/자격정보/네트워크 상태 확인
|
|
3. 최근 코드 변경 사항 확인
|
|
4. 원문 payload 1건을 replay 하여 문제 재현
|
|
5. 필요 시 해당 job freeze 후 다른 source는 계속 진행
|
|
|
|
## 6. Quarantine 처리
|
|
|
|
### 확인 항목
|
|
|
|
- 어떤 source인가
|
|
- 어떤 object type인가
|
|
- 언제부터 발생했는가
|
|
- 동일 원인 반복인가
|
|
|
|
### 절차
|
|
|
|
1. quarantine raw와 sidecar 열람
|
|
2. schema violation 또는 필수 필드 누락 원인 파악
|
|
3. 파서/정규화 로직 수정 필요 여부 판단
|
|
4. 수정 후 replay 수행
|
|
5. 정상 결과 확인 시 quarantine 해제 또는 새 run으로 재처리
|
|
|
|
## 7. Checkpoint 복구
|
|
|
|
### 증상
|
|
|
|
- 이미 처리한 데이터를 계속 다시 가져옴
|
|
- 새 데이터가 안 들어옴
|
|
- 특정 source만 오래 lag 발생
|
|
|
|
### 절차
|
|
|
|
1. 현재 checkpoint 값 백업
|
|
2. 최근 성공 run 기준 정상 위치 확인
|
|
3. 필요한 경우 checkpoint reset 실행
|
|
4. 작은 범위 backfill로 검증
|
|
5. 문제 없으면 정상 poll 재개
|
|
|
|
주의:
|
|
- checkpoint reset은 운영자 수동 승인 후에만 수행
|
|
- reset 전 snapshot 기록 필수
|
|
|
|
## 8. Replay 절차
|
|
|
|
Replay는 raw를 다시 해석하거나 구조화할 때 사용합니다.
|
|
|
|
예:
|
|
|
|
```bash
|
|
python -m apps.collector.sec_collector.main \
|
|
--mode replay \
|
|
--raw-path data/raw/sec/2026-03-12/.../filing.txt
|
|
```
|
|
|
|
확인할 것:
|
|
- replay run_id가 따로 생성되었는가
|
|
- 외부 API 호출이 발생하지 않았는가
|
|
- structured row가 기대한 대로 갱신되었는가
|
|
|
|
## 9. 데이터 이상 탐지 시 판단 기준
|
|
|
|
### SEC
|
|
|
|
- 특정 대형 종목 filing이 비정상적으로 누락됨
|
|
- filing_date 또는 accession 누락
|
|
- 99.1 artifact가 갑자기 전부 사라짐
|
|
|
|
### Alpaca
|
|
|
|
- 전일 bars가 없거나 너무 적음
|
|
- OHLC 순서 이상
|
|
- volume이 0 또는 과도하게 작음
|
|
|
|
### FRED
|
|
|
|
- 최신 observation이 지나치게 오래 갱신되지 않음
|
|
- series metadata가 바뀜
|
|
|
|
### FINRA
|
|
|
|
- 파일 헤더 형식 변경
|
|
- symbol row 급감
|
|
- ratio 계산 불가 행 급증
|
|
|
|
## 10. 일시적 중단(Freeze/Drain)
|
|
|
|
### Freeze
|
|
|
|
신규 실행을 즉시 막습니다.
|
|
|
|
### Drain
|
|
|
|
현재 실행만 마무리하고 다음 스케줄부터 멈춥니다.
|
|
|
|
사용 예:
|
|
- source 응답 포맷 변화 의심
|
|
- 저장 계층 장애
|
|
- 코드 배포 직후 이상 발견
|
|
|
|
## 11. 운영자가 반드시 남겨야 하는 기록
|
|
|
|
- 문제 발생 시각
|
|
- 영향 받은 source/job
|
|
- 영향 범위(날짜/심볼/CIK)
|
|
- 임시 조치
|
|
- 영구 수정 필요 여부
|
|
- replay/backfill 수행 여부
|
|
|
|
## 12. 운영 종료 체크
|
|
|
|
- 실패 run이 남아 있지 않은가
|
|
- checkpoint lag가 허용 범위 내인가
|
|
- quarantine 신규 건이 있는가
|
|
- raw/staging/structured count가 대체로 합리적인가
|
|
- 다음 배치를 막는 freeze가 켜져 있지 않은가
|