collector-hj3415 0.2.2

Collector runtime utilities for hj3415

collector-hj3415

collector-hj3415는 수집(collector) 작업 운영에 필요한 공통 유틸리티를 제공하는 파이썬 라이브러리 패키지입니다.
MongoDB 상태 확인, 배치 실행 이력 기록, Telegram 실패 알림, 일/주간 메일 리포트 기능을 공통으로 묶어 재사용할 수 있습니다.

1) 프로젝트 기능 (사용자 관점)

• MongoDB 준비 상태를 확인해, 수집 잡 시작 전에 연결 가능 여부를 점검합니다.
• 현재 UTC 시각(asof)을 생성해 잡 실행 기준 시점을 통일합니다.
• 잡 실행 결과(성공/실패, 실행 시간, 메시지)를 job_runs 컬렉션에 저장합니다.
• 동일 장애 메시지에 대해 쿨다운을 적용해 Telegram 알림 중복 폭주를 줄입니다.
• 누적된 실행 이력을 바탕으로 일간/주간 요약 메일을 발송합니다.

2) 프로젝트 구조 (쉽게 보기)

packages/collector-hj3415/
├─ src/collector_hj3415/
│  ├─ cli.py          # 핵심 기능 + CLI 엔트리포인트
│  ├─ __main__.py     # python -m collector_hj3415 실행 진입점
│  └─ __init__.py
├─ pyproject.toml     # 패키지 메타데이터/의존성 정의
└─ README.md

• 실제 기능 구현은 대부분 cli.py에 있습니다.
• 콘솔 스크립트 엔트리 등록은 없고, python -m collector_hj3415.cli ... 형태로 실행합니다.

3) 설치

프로젝트 루트 기준:

pip install -e ./packages/collector-hj3415

또는 배포된 wheel/tar.gz가 있다면 일반 pip install 방식으로 설치할 수 있습니다.

4) CLI 사용법

기본 형식:

python -m collector_hj3415.cli <command> [options]

4.1 MongoDB 준비 대기

python -m collector_hj3415.cli wait-mongo --timeout-sec 90

• 지정 시간 내 ping 성공 시 0, 실패 시 1을 반환합니다.

4.2 현재 UTC 시각 생성

python -m collector_hj3415.cli gen-asof-utc

• ISO-8601 UTC 문자열을 출력합니다.

4.3 Universe 존재 여부 확인

python -m collector_hj3415.cli universe-exists --universe krx300

• universe_latest 컬렉션에서 _id=krx300 존재 시 0, 없으면 1 반환.

4.4 잡 실행 결과 기록

python -m collector_hj3415.cli record-job-run \
  --job-name scraper_daily_c101 \
  --status ok \
  --started-epoch 1711700000 \
  --ended-epoch 1711700100 \
  --message "completed"

4.5 Telegram 실패 알림 (쿨다운 포함)

python -m collector_hj3415.cli notify-telegram-failure \
  --job-name scraper_daily_c101 \
  --message "failed with exit=1"

• TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID 미설정 시 전송 없이 0 반환.
• 쿨다운 중이면 2 반환.
• 전송 실패 시 1 반환.

4.6 일간/주간 메일 리포트 발송

python -m collector_hj3415.cli send-report daily
python -m collector_hj3415.cli send-report weekly

• MongoDB job_runs 데이터를 집계해 메일 본문을 만들고 SMTP로 전송합니다.

5) 테스트 실행

5.1 Smoke Test (Mocking)

개발 환경에서 외부 의존성 없이 로직의 정상 동작을 확인하기 위해 pytest를 사용할 수 있습니다.

# 패키지 루트에서 실행
cd packages/collector-hj3415
pytest tests/test_cli.py

5.2 Integration Test (Real Network)

실제 MongoDB, Telegram, SMTP 서버와의 연동을 확인하기 위한 테스트입니다. src/collector_hj3415/.env 파일에 유효한 설정이 있어야 합니다.

# 패키지 루트에서 실행
cd packages/collector-hj3415
pytest tests/test_cli_integration.py -v

• MongoDB: 설정된 MONGO_URI로 실제 연결 및 데이터 기록을 테스트합니다.
• Telegram: 실제 Bot Token과 Chat ID를 사용하여 메시지를 전송합니다.
• SMTP: 설정된 메일 서버를 통해 실제 메일 발송을 테스트합니다. (실패 시 skip 처리됨)

6) 다른 프로젝트에서 임포트해서 사용하기

collector 하위 배치 프로젝트에서 공통으로 사용하는 방식입니다.

5.1 파이썬 코드에서 직접 호출

from collector_hj3415.cli import wait_mongo, record_job_run
import time

if wait_mongo(timeout_sec=60) != 0:
    raise SystemExit("MongoDB is not ready")

started = int(time.time())
# ... 실제 작업 수행 ...
ended = int(time.time())

record_job_run(
    job_name="my_batch_job",
    status="ok",
    started_epoch=started,
    ended_epoch=ended,
    message="done",
)

5.2 셸 스크립트에서 모듈 CLI 호출

python3 -m collector_hj3415.cli wait-mongo --timeout-sec 90
python3 -m collector_hj3415.cli record-job-run \
  --job-name "my_job" \
  --status "fail" \
  --started-epoch "$started" \
  --ended-epoch "$ended" \
  --message "error message"

6) 환경변수 설정

아래 값들은 미지정 시 기본값으로 동작합니다.

변수명	기본값	설명
MONGO_URI	mongodb://mongo:27017	MongoDB 연결 URI
MONGO_DB_NAME	hj3415	DB 이름
SERVICE_NAME	collector	서비스/잡 소속 이름
JOB_RUNS_COLLECTION	job_runs	잡 실행 이력 컬렉션
JOB_ALERTS_COLLECTION	job_alerts	Slack 알림 쿨다운 상태 컬렉션
ALERT_COOLDOWN_MIN	60	동일 알림 메시지 쿨다운(분)
TELEGRAM_BOT_TOKEN	빈 값	Telegram Bot API Token
TELEGRAM_CHAT_ID	빈 값	Telegram Chat ID
SMTP_HOST	빈 값	SMTP 호스트 (미설정 시 메일 발송 스킵)
SMTP_PORT	587	SMTP 포트
SMTP_USE_TLS	true	TLS 사용 여부
SMTP_USERNAME	빈 값	SMTP 사용자
SMTP_PASSWORD	빈 값	SMTP 비밀번호
MAIL_FROM	collector@localhost 또는 SMTP_USERNAME	발신자 주소
MAIL_TO_DAILY	빈 값	일간 리포트 수신자(쉼표 구분)
MAIL_TO_WEEKLY	빈 값	주간 리포트 수신자(쉼표 구분)

예시:

export MONGO_URI="mongodb://localhost:27017"
export MONGO_DB_NAME="hj3415"
export SERVICE_NAME="collector-scraper-daily"
export TELEGRAM_BOT_TOKEN="123456789:ABCDEF..."
export TELEGRAM_CHAT_ID="987654321"
export ALERT_COOLDOWN_MIN="60"

export SMTP_HOST="smtp.gmail.com"
export SMTP_PORT="587"
export SMTP_USE_TLS="true"
export SMTP_USERNAME="[e-mail]"
export SMTP_PASSWORD="app-password"
export MAIL_FROM="[e-mail]"
export MAIL_TO_DAILY="[e-mail],[e-mail]"
export MAIL_TO_WEEKLY="[e-mail]"

참고

이 패키지는 단독 애플리케이션이 아닌 라이브러리 성격의 공통 모듈이므로, Dockerfile/docker-compose 조합 사용법은 이 문서에서 다루지 않습니다.