raw_block CI 커버리지 & 실장 테스트 가이드
[!tldr] 업무 관점 takeaway raw_block PR을 올릴 때 GitHub Actions CI 통과 ≠ 완전 검증. O_DIRECT, io_uring, 멀티프로세스, 주기적 체크포인트 스레드 등 핵심 경로가 PR CI에서 모두 제외된다. HC SSD / NVMe 경로를 건드린다면 반드시 로컬 실장 테스트가 추가로 필요하며, 이를 빠뜨리면 CI 녹색에도 불구하고 실 환경에서 버그가 날 수 있다.
PR CI 구조 요약
모든 워크플로우는 .github/workflows/에 있고 dorny/paths-filter로 관련 경로 변경 시에만 job을 실행한다.
PR마다 자동으로 도는 것 (draft 포함)
| 워크플로우 | 트리거 조건 | 실행 내용 |
|---|---|---|
code_quality_checks.yml | 모든 PR | pre-commit --all-files (isort, ruff, mypy, SPDX, torch 직접 사용 금지, clang-format) |
test.yml → test job | **.py, pyproject.toml, requirements 변경 | non-CUDA 유닛테스트, Python 3.10/3.11/3.12/3.13 × ubuntu |
test.yml → raw-block-tests job | raw_block 관련 파일 변경 시만 | Rust 익스텐션 빌드 후 raw_block 특화 테스트 3개만 실행 |
macos_compat.yml | PR (관련 변경) | macOS CPU-only smoke test |
codeql.yml | PR / 스케줄 | Python + Actions 정적 보안 분석 |
CI에서 --ignore로 제외되는 테스트
tests/disagg/
tests/v1/multiprocess/
tests/v1/distributed/
tests/v1/mp_observability/
tests/skipped/
tests/cli/commands/trace/
tests/v1/storage_backend/test_eic.py
tests/v1/storage_backend/test_p2p_backend_with_controller.py
raw-block-tests job에서는
test_raw_block_l2_adapter.py(멀티프로세스 디렉토리 안) 한 파일만 예외적으로 실행된다.
raw_block 테스트 커버리지
총 5개 파일. raw-block-tests CI job에서 3개, 표준 test job에서 2개 실행.
커버되는 것
- 기본 CRUD:
put_many/load_many_into/exists_many/delete_many - 중복 put: 원본 payload 보존
- Checkpoint: 저장·복구, 손상 대체, 무효 항목 스킵, 레거시 dtype 복구
- Lock refcount / pin·unpin
- 배치 remove:
forceflag 동작 - TP(Tensor Parallelism): 멀티 GPU per-tp device 경로
- Device I/O: POSIX
pread/pwrite, io_uring batched 읽기/쓰기, 용량 초과 에러 - Key codec:
ObjectKey↔ 문자열 라운드트립
커버 안 되는 것
| 미커버 항목 | 비고 |
|---|---|
_checkpoint_loop() — 주기적 체크포인트 스레드 | 모든 테스트에서 meta_enable_periodic=False |
| O_DIRECT 경로 전반 | LMCACHE_RUN_ODIRECT_SMOKE=1 설정 시만 opt-in 실행 |
normalize_raw_block_io_engine() / validate_raw_block_io_options() | 설정 검증 함수 자체가 테스트 없음 |
| io_uring 미지원 환경 폴백 | "best-effort skip" 로직 존재하지만 강제 장애 시나리오 없음 |
| 동시 put/delete 경합 상태 | race condition 시나리오 없음 |
_snapshot_state() lock hold 시간 | 인덱스 대용량(1만+ entry) 시 성능 미검증 |
실장 테스트가 필요한 경우
아래 변경 유형은 CI 통과해도 실제 동작 보장 불가. PR 올리기 전 로컬 또는 실장 환경에서 직접 확인해야 한다.
GPU / CUDA 경로
rust/raw_block/ Rust 익스텐션(io_uring, O_DIRECT 등) 수정 시:
pytest tests/v1/storage_backend/test_rust_raw_block_backend.py -xvs
멀티프로세스 파이프라인
lmcache/v1/multiprocess/, lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py 수정 시:
pytest -xvs tests/v1/multiprocess/ --ignore=tests/v1/multiprocess/test_gpu_context.py
주기적 체크포인트 스레드
_checkpoint_loop() / meta_enable_periodic 관련 코드 — 모든 테스트에서 비활성화 상태. meta_enable_periodic=True로 명시적 통합 테스트 작성 또는 수동 검증 필요.
O_DIRECT / io_uring 경로
LMCACHE_RUN_ODIRECT_SMOKE=1 pytest -xvs tests/v1/storage_backend/test_raw_block_device.py
변경 매핑 요약
| 수정 파일/디렉토리 | CI 커버 | 실장 필요 |
|---|---|---|
rust/raw_block/ — 기본 put/get/checkpoint | ✅ raw-block-tests | GPU: io_uring / O_DIRECT 경로 별도 확인 |
lmcache/v1/storage_backend/raw_block/core.py | ✅ test job | 주기적 체크포인트 경로 별도 확인 |
lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py | ✅ test job | MP 경로 사용 시 multiprocess 테스트 확인 |
lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py | ⚠️ L2 adapter 일부만 | multiprocess 경로 직접 확인 |
lmcache/v1/multiprocess/** | ❌ PR CI skip | 로컬에서 tests/v1/multiprocess/ 직접 실행 |
lmcache/v1/distributed/** | ❌ PR CI skip | 로컬에서 tests/v1/distributed/ 직접 실행 |
| CUDA / GPU 익스텐션 | ❌ GPU 러너 없음 | GPU 장비 필수 |
멀티프로세스 / 분산 테스트 구조
PR CI (GitHub Actions, 공개)
└─ test.yml: multiprocess/distributed 전부 --ignore
└─ raw-block-tests: test_raw_block_l2_adapter.py 한 파일만
K3 파이프라인 (내부 CI, 비공개)
└─ 실제 멀티프로세스 + GPU 테스트
└─ 외부 기여자 기준 블랙박스
disagg (tests/disagg/)
└─ NIXL 기반, 어느 공개 CI에도 포함 안 됨
- multiprocess 테스트: subprocess 스폰 + ZMQ IPC 기반. 5GB 공유
MixedMemoryAllocatorsession-scoped fixture. - distributed 테스트: 단일 프로세스 in-memory 시뮬레이션. GPU 없이 실행 가능.
- disagg 테스트: NIXL 라이브러리 필수.