7.2 KiB
7.2 KiB
모의투자 API 안전 운영 가이드
한국투자증권 모의투자 API를 안전하고 안정적으로 운영하기 위한 재시도 및 쓰로틀링 전략이 적용되어 있습니다.
주요 기능
1. 안전한 재시도 전략 (Exponential Backoff)
- 재시도 횟수 제한: 최대 3회 (설정 가능)
- 점진적 백오프: 재시도 간격이 지수적으로 증가 (1.5초 → 3초 → 6초)
- 오류 유형 분별:
- 429 (Rate Limit), 5xx (서버 오류): 재시도 실행
- 4xx (클라이언트 오류, 인증 실패): 즉시 종료
- 타임아웃 처리: 30초 타임아웃 + 재시도 로직
2. 쓰로틀링 전략
- 초당 호출 제한: 기본 0.5초 간격 (초당 2회 권장)
- 동시 요청 제한: 최대 2건의 동시 요청 (세마포어 사용)
- 자동 간격 조절: 마지막 요청 시간 기반 자동 대기
3. 모니터링 & 경고
- 실시간 통계 수집: 총 호출 수, 오류율, 재시도 횟수, 평균 응답 시간
- 오류율 경고: 30% 초과 시 자동 경고
- API 상태 체크 엔드포인트:
/api/v1/monitoring/api-stats
환경 변수 설정
.env 파일에 다음 설정을 추가하여 조절할 수 있습니다:
# API 재시도 설정
API_MAX_RETRIES=3 # 최대 재시도 횟수 (기본: 3)
API_RETRY_DELAY=1.5 # 초기 재시도 대기 시간(초) (기본: 1.5)
API_RETRY_BACKOFF=2.0 # 지수 백오프 배율 (기본: 2.0)
# API 쓰로틀링 설정
API_MIN_REQUEST_INTERVAL=0.5 # 최소 요청 간격(초) - 초당 2회 (기본: 0.5)
API_MAX_CONCURRENT_REQUESTS=2 # 동시 최대 요청 수 (기본: 2)
API_TIMEOUT=30.0 # API 타임아웃(초) (기본: 30.0)
# 모니터링 설정
API_ERROR_THRESHOLD=0.3 # 오류율 경고 임계값 (기본: 30%)
API_MONITORING_WINDOW=100 # 모니터링 윈도우 크기 (기본: 100개 요청)
API 사용 예시
기본 사용 (자동 재시도 + 쓰로틀링)
from app.services.korea_investment_api import korea_investment_api
# 현재가 조회 (자동 재시도 및 쓰로틀링 적용)
result = await korea_investment_api.get_current_price("005930")
# 일봉 데이터 조회
chart = await korea_investment_api.get_daily_chart("005930")
# 종목 리스트 조회
stocks = await korea_investment_api.get_stock_list("J") # KOSPI
통계 조회
# API 호출 통계 확인
stats = korea_investment_api.get_monitor_stats()
print(f"총 호출: {stats['total_calls']}건")
print(f"오류율: {stats['error_rate']:.1%}")
print(f"평균 응답 시간: {stats['avg_duration']:.2f}초")
# 로그에 통계 출력
korea_investment_api.log_monitor_stats()
모니터링 API 엔드포인트
1. API 통계 조회
GET http://localhost:8000/api/v1/monitoring/api-stats
응답 예시:
{
"status": "healthy",
"stats": {
"total_calls": 150,
"total_errors": 5,
"total_retries": 8,
"error_rate": 0.033,
"avg_duration": 1.25,
"recent_calls": 100
},
"message": "오류율: 3.3%, 평균 응답: 1.25초"
}
2. 헬스체크
GET http://localhost:8000/api/v1/monitoring/health
응답 예시:
{
"status": "healthy",
"error_rate": 0.033,
"total_calls": 150,
"timestamp": "2025-11-10T09:30:00"
}
3. 통계 로깅
POST http://localhost:8000/api/v1/monitoring/log-stats
배치 스크립트 실행
매일 아침 9시 전체 종목 분석을 실행하는 배치 스크립트:
테스트 실행 (10개 종목만)
cd backend
python batch_daily_analysis.py --test
제한된 수 실행
python batch_daily_analysis.py --limit 50
전체 실행
python batch_daily_analysis.py
Cron 스케줄 설정 (매일 평일 오전 9시)
crontab -e
다음 라인 추가:
0 9 * * 1-5 cd /path/to/auto-stock/backend && /path/to/python batch_daily_analysis.py >> /path/to/logs/batch.log 2>&1
로그 확인
배치 스크립트 실행 시 다음과 같은 상세 로그를 확인할 수 있습니다:
2025-11-10 09:00:00 - INFO - 🚀 Starting daily batch analysis for 2025-11-10
2025-11-10 09:00:00 - INFO - ⚙️ Rate Limiting: 0.5초 간격, 최대 재시도 3회
2025-11-10 09:00:05 - INFO - ✅ Found 30 KOSPI stocks
2025-11-10 09:00:10 - INFO - ✅ Found 30 KOSDAQ stocks
2025-11-10 09:00:10 - INFO - 📊 Total tradable stocks: 60
2025-11-10 09:00:15 - INFO - [1/60] Analyzing 005930 (삼성전자)...
2025-11-10 09:00:16 - INFO - ✅ Saved analysis for 005930 (삼성전자): score=5
...
2025-11-10 09:02:30 - INFO - ============================================================
2025-11-10 09:02:30 - INFO - ✅ Batch analysis completed!
2025-11-10 09:02:30 - INFO - 📊 Success: 58 / Total: 60
2025-11-10 09:02:30 - INFO - ❌ Failed: 2
2025-11-10 09:02:30 - INFO - ⏱️ Duration: 145.2 seconds (2.4 minutes)
2025-11-10 09:02:30 - INFO - 📡 API 통계:
2025-11-10 09:02:30 - INFO - - 총 호출: 122건
2025-11-10 09:02:30 - INFO - - 오류: 3건 (2.5%)
2025-11-10 09:02:30 - INFO - - 재시도: 5건
2025-11-10 09:02:30 - INFO - - 평균 응답 시간: 1.18초
문제 해결
1. 오류율이 높을 때 (30% 이상)
- 원인: API 서버 불안정 또는 네트워크 문제
- 해결책:
API_RETRY_DELAY를 2~3초로 증가API_MAX_RETRIES를 5회로 증가API_MIN_REQUEST_INTERVAL을 1초로 증가 (호출 빈도 낮춤)
# .env 파일 수정
API_RETRY_DELAY=2.5
API_MAX_RETRIES=5
API_MIN_REQUEST_INTERVAL=1.0
2. 타임아웃 빈발
- 원인: 네트워크 지연 또는 API 응답 느림
- 해결책: 타임아웃 시간 증가
API_TIMEOUT=60.0
3. Rate Limit 초과 (429 에러)
- 원인: 요청 간격이 너무 짧음
- 해결책: 요청 간격 증가
API_MIN_REQUEST_INTERVAL=1.0 # 초당 1회로 제한
API_MAX_CONCURRENT_REQUESTS=1 # 동시 요청 1건으로 제한
성능 튜닝 팁
안정성 우선 (추천)
API_MIN_REQUEST_INTERVAL=0.5
API_MAX_CONCURRENT_REQUESTS=2
API_MAX_RETRIES=3
API_RETRY_DELAY=1.5
속도 우선 (주의)
API_MIN_REQUEST_INTERVAL=0.3
API_MAX_CONCURRENT_REQUESTS=3
API_MAX_RETRIES=2
API_RETRY_DELAY=1.0
대규모 배치용 (안전 중시)
API_MIN_REQUEST_INTERVAL=1.0
API_MAX_CONCURRENT_REQUESTS=1
API_MAX_RETRIES=5
API_RETRY_DELAY=2.0
API_RETRY_BACKOFF=3.0
추가 모니터링
Prometheus + Grafana 연동 (선택 사항)
API 통계를 Prometheus 형식으로 내보내려면 /api/v1/monitoring/metrics 엔드포인트를 추가 구현할 수 있습니다.
알림 설정 (선택 사항)
오류율이 임계값을 초과할 때 Slack/Email 알림을 보내도록 확장 가능합니다.
참고 자료
문의 및 피드백: 시스템 운영 중 문제가 발생하면 로그 파일과 API 통계를 함께 확인하세요.