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.

4.5 KiB

Raw Blame History

Phase 2 운영 Runbook

1. 목적

이 문서는 운영자가 Phase 2 수집 파이프라인을 실행, 점검, 재시도, 복구할 때 따르는 절차를 정의합니다.

2. 일일 운영 루틴

장 전 / 오전

SEC submissions poll 정상 동작 여부 확인
전일 FINRA 파일 수집 완료 여부 확인
FRED 최신 observation lag 확인
source freeze 설정이 의도치 않게 켜져 있지 않은지 확인

장 후

Alpaca daily bars 적재 완료 여부 확인
SEC 신규 filing 유입량 점검
실패 잡 및 quarantine 건수 확인
데이터 품질 검증 리포트 확인

3. 기본 확인 명령

예시 명령은 프로젝트 CLI 이름에 맞게 조정합니다.

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

python -m apps.collector.sec_collector.main --mode poll --run-id MANUAL_SEC_POLL_001

Alpaca daily backfill

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

python -m apps.collector.fred_collector.main --mode poll

FINRA fetch

python -m apps.collector.finra_collector.main --mode poll

5. 실패 시 대응 절차

5.1 단일 run 실패

job_runs에서 상태와 오류 유형 확인
raw 파일이 쓰였는지 확인
checkpoint가 잘못 전진했는지 확인
retriable 이면 동일 파라미터로 재시도
terminal 이면 source payload와 schema drift 여부 확인

5.2 같은 잡이 연속 실패

source freeze 여부 확인
환경변수/자격정보/네트워크 상태 확인
최근 코드 변경 사항 확인
원문 payload 1건을 replay 하여 문제 재현
필요 시 해당 job freeze 후 다른 source는 계속 진행

6. Quarantine 처리

확인 항목

어떤 source인가
어떤 object type인가
언제부터 발생했는가
동일 원인 반복인가

절차

quarantine raw와 sidecar 열람
schema violation 또는 필수 필드 누락 원인 파악
파서/정규화 로직 수정 필요 여부 판단
수정 후 replay 수행
정상 결과 확인 시 quarantine 해제 또는 새 run으로 재처리

7. Checkpoint 복구

증상

이미 처리한 데이터를 계속 다시 가져옴
새 데이터가 안 들어옴
특정 source만 오래 lag 발생

절차

현재 checkpoint 값 백업
최근 성공 run 기준 정상 위치 확인
필요한 경우 checkpoint reset 실행
작은 범위 backfill로 검증
문제 없으면 정상 poll 재개

주의:

checkpoint reset은 운영자 수동 승인 후에만 수행
reset 전 snapshot 기록 필수

8. Replay 절차

Replay는 raw를 다시 해석하거나 구조화할 때 사용합니다.

예:

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가 켜져 있지 않은가

4.5 KiB Raw Blame History