실전 트러블슈팅 가이드
HPP Production Workflows - 실전 트러블슈팅 가이드
개요
본 문서는 HPP Production Workflows를 AWS HealthOmics에서 실행할 때 발생할 수 있는 실제 문제들과 해결 방법을 다룹니다. 실제 프로덕션 환경에서 발생한 사례들을 바탕으로 구체적인 해결책을 제시합니다.
1. WDL 워크플로우 호환성 문제
문제 1: OutputError - 작업 디렉토리 외부 경로 참조
에러 메시지:
OutputError: task outputs attempted to use a path outside its working directory:
output_final/NA20799.m64306Ue_220927_182256.dc.q20.fastq.gz
근본 원인:
- 심볼릭 링크가 작업 디렉토리 외부의 파일을 참조
- HealthOmics 보안 정책 위반
문제가 있는 코드:
# 문제: 외부 파일에 대한 심볼릭 링크 생성
ln -s ~{readFile} output/${PREFIX}.gz # /mnt/inputs/file.gz 참조
# 나중에 또 다른 심볼릭 링크 생성
ln output/${OUTPUT_NAME} output_final/${OUTPUT_NAME}
# 결과: output_final/file.gz → output/file.gz → /mnt/inputs/file.gz (외부)
해결 방법:
Option 1: 파일 복사 (안전하지만 느림)
elif [[ "$SUFFIX" == "gz" ]] ; then
cp ~{readFile} output/${PREFIX}.gz # 파일 복사
fi
Option 2: 하드 링크 + 폴백 (권장)
elif [[ "$SUFFIX" == "gz" ]] ; then
# 하드 링크 시도, 실패 시 복사
ln ~{readFile} output/${PREFIX}.gz 2>/dev/null || \
cp ~{readFile} output/${PREFIX}.gz
fi
Option 3: 조건부 처리
if [ "~{excludeString}" != "" ]; then
# 필터링이 필요한 경우 직접 처리
zcat ~{readFile} | grep -v "~{excludeString}" | pigz -p~{threadCount} > output/${PREFIX}.gz
else
# 필터링이 불필요한 경우 복사
cp ~{readFile} output/${PREFIX}.gz
fi
문제 2: 불안정한 파일 발견 로직
문제가 있는 코드:
OUTPUT_NAME=$(ls output) # 여러 파일이 있으면 실패
mv output/${OUTPUT_NAME} output_final/${OUTPUT_NAME}
문제점:
ls output이 여러 파일을 반환하면 변수에 공백으로 구분된 여러 값 저장- 파일이 없으면 에러 메시지 반환
- 심볼릭 링크의 유효성 검증 안 함
해결 방법:
# 안정적인 파일 발견
OUTPUT_FILE=$(find output -type f -o -type l | head -1)
if [ -z "${OUTPUT_FILE}" ]; then
echo "Error: No output file found in output directory" >&2
exit 1
fi
OUTPUT_NAME=$(basename "${OUTPUT_FILE}")
if [ "~{excludeString}" != "" ]; then
zcat "${OUTPUT_FILE}" | grep -v "~{excludeString}" | pigz -p~{threadCount} > output_final/${OUTPUT_NAME}
else
mv "${OUTPUT_FILE}" output_final/${OUTPUT_NAME}
fi
문제 3: WDL Output 섹션의 외부 참조
문제가 있는 코드:
output {
File extractedRead = flatten([glob("output_final/*"), [readFile]])[0]
Int fileSizeGB = read_int("outputsize")
}
문제점:
[readFile]폴백이 외부 파일 참조glob("output_final/*")가 빈 배열을 반환하면 외부 파일 사용
해결 방법:
output {
File extractedRead = glob("output_final/*")[0] # 폴백 제거
Int fileSizeGB = read_int("outputsize")
}
2. ECR 권한 문제
문제: ECR_PERMISSION_ERROR
에러 메시지:
ECR_PERMISSION_ERROR: Unable to pull image from ECR repository
근본 원인:
- ECR 리포지토리에 HealthOmics 서비스 주체 권한 없음
해결 방법:
# 각 ECR 리포지토리에 HealthOmics 권한 추가
aws ecr set-repository-policy \
--repository-name hpp/hifiasm \
--region ap-northeast-2 \
--policy-text '{
"Version": "2012-10-17",
"Statement": [{
"Sid": "HealthOmicsAccess",
"Effect": "Allow",
"Principal": {"Service": "omics.amazonaws.com"},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchCheckLayerAvailability"
]
}]
}'
자동화 스크립트:
#!/bin/bash
REPOSITORIES=(
"hpp/hifiasm"
"hpp/deeppolisher"
"hpp/ntsm"
"hpp/cutadapt"
"hpp/minimap2"
"hpp/samtools"
"hpp/merqury"
"hpp/compleasm"
"hpp/yak"
)
for repo in "${REPOSITORIES[@]}"; do
echo "Adding HealthOmics permissions to $repo..."
aws ecr set-repository-policy \
--repository-name "$repo" \
--region ap-northeast-2 \
--policy-text '{
"Version": "2012-10-17",
"Statement": [{
"Sid": "HealthOmicsAccess",
"Effect": "Allow",
"Principal": {"Service": "omics.amazonaws.com"},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchCheckLayerAvailability"
]
}]
}'
done
3. 성능 및 타임아웃 문제
문제: miniWDL Docker Cleanup 타임아웃
증상:
- 모든 작업이 성공적으로 완료됨
- Docker cleanup 단계에서 900초(15분) 타임아웃 발생
- 워크플로우가 실패로 표시됨
타임라인 예시:
Task 완료: 05:38:20
Docker task complete: 05:38:20
타임아웃 에러: 05:53:20 (정확히 15분 후)
근본 원인:
- miniWDL이 Docker 컨테이너 실행 후 파일 소유권 변경(
chown) 시도 - 대용량 파일 처리로 인한 시스템 부하
- Docker API 응답 지연
해결 방법 1: 타임아웃 증가
# .miniwdl.cfg 파일 생성
[scheduler]
container_timeout = 3600 # 1시간으로 증가
[docker_swarm]
auto_init = true
[call_cache]
enable = true
dir = /tmp/miniwdl_call_cache
[download_cache]
enable = true
dir = /tmp/miniwdl_download_cache
해결 방법 2: as_user 모드 사용
[task_runtime]
as_user = true # chown 단계 건너뛰기
해결 방법 3: Docker 데몬 최적화
# /etc/docker/daemon.json
{
"max-concurrent-downloads": 3,
"max-concurrent-uploads": 5,
"storage-driver": "overlay2",
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}
문제: 메모리 부족으로 인한 작업 실패
에러 메시지:
Task failed with exit code 137 (SIGKILL - out of memory)
해결 방법:
동적 메모리 할당:
task hifiasm_assembly {
input {
File hifi_reads
Int estimated_genome_size = 3000000000
}
# 파일 크기 기반 리소스 계산
Int file_size_gb = ceil(size(hifi_reads, "GB"))
Int memory_gb = if file_size_gb > 50 then 512 else 256
Int cpu_count = if file_size_gb > 50 then 64 else 32
runtime {
docker: "humanpangenomics/hifiasm:latest"
memory: memory_gb + " GB"
cpu: cpu_count
# 메모리 부족 시 자동 재시도
maxRetries: 2
memory_retry_multiplier: 1.5
}
}
HealthOmics 리소스 최적화:
{
"parameters": {
"hifiasm_assembly.memory_gb": 512,
"hifiasm_assembly.cpu_count": 64,
"hifiasm_assembly.disk_gb": 1000
}
}
4. 스토리지 최적화 문제
문제: DYNAMIC 스토리지 성능 저하
증상:
- I/O 집약적 작업에서 성능 저하
- 예측 불가능한 실행 시간
해결 방법: STATIC 스토리지 전환
전환 기준:
STATIC 스토리지 권장 조건:
- 월 10회 이상 반복 실행
- 예측 가능한 데이터 크기
- 높은 IOPS 요구사항 (>7,000)
- 일관된 성능 필요
크기 계산:
# 3-5회 DYNAMIC 실행 후 평균 사용량 측정
# 20% 버퍼 추가
AVERAGE_USAGE_GB=800
STATIC_SIZE_GB=$((AVERAGE_USAGE_GB * 120 / 100)) # 960GB
# 1200GB 단위로 반올림 (HealthOmics 요구사항)
STATIC_SIZE_GB=1200
워크플로우 생성 시 STATIC 설정:
aws omics start-run \
--workflow-id <workflow-id> \
--role-arn arn:aws:iam::123456789012:role/OmicsUnifiedJobRole \
--name "optimized-run" \
--output-uri s3://bucket/outputs/ \
--storage-type STATIC \
--storage-capacity 1200 \
--parameters file://inputs.json \
--region ap-northeast-2
문제: 중간 파일로 인한 스토리지 부족
해결 방법: 임시 파일 정리
# WDL 태스크에서 중간 파일 정리
command <<<
# 주요 작업 수행
hifiasm -o assembly -t ${cpu} ${hifi_reads}
# 중간 파일 정리 (선택적)
rm -f *.ec.bin *.ovlp.source.bin *.ovlp.reverse.bin
# 최종 결과만 유지
mv assembly.bp.p_ctg.gfa output/
mv assembly.bp.a_ctg.gfa output/
>>>
5. 네트워크 및 데이터 전송 문제
문제: 대용량 데이터 전송 지연
증상:
- 200GB+ 데이터 업로드에 2-4시간 소요
- 워크플로우 시작 지연
해결 방법:
S3 Transfer Acceleration 활용:
# Transfer Acceleration 활성화
aws s3api put-bucket-accelerate-configuration \
--bucket your-genomics-data-bucket \
--accelerate-configuration Status=Enabled
# 클라이언트 설정
aws configure set s3.use_accelerate_endpoint true
aws configure set s3.multipart_threshold 64MB
aws configure set s3.multipart_chunksize 16MB
aws configure set s3.max_concurrent_requests 20
병렬 업로드 최적화:
# 대용량 파일 병렬 업로드
aws s3 cp large_file.fastq.gz s3://bucket/data/ \
--storage-class STANDARD_IA \
--metadata "sample=HG002,type=hifi"
리전 내 데이터 배치:
# 동일 리전 내 S3 버킷 사용
aws s3 mb s3://genomics-data-ap-northeast-2 --region ap-northeast-2
6. 모니터링 및 디버깅 전략
실시간 모니터링 설정
CloudWatch 대시보드:
{
"widgets": [
{
"type": "metric",
"properties": {
"metrics": [
["AWS/Omics", "RunDuration", "WorkflowId", "your-workflow-id"],
[".", "TaskFailureRate", ".", "."],
[".", "StorageUtilization", ".", "."]
],
"period": 300,
"stat": "Average",
"region": "ap-northeast-2",
"title": "HealthOmics Workflow Metrics"
}
}
]
}
자동 알림 설정:
# SNS 토픽 생성
aws sns create-topic --name genomics-alerts --region ap-northeast-2
# CloudWatch 알람 생성
aws cloudwatch put-metric-alarm \
--alarm-name "HealthOmics-RunFailure" \
--alarm-description "Alert when HealthOmics run fails" \
--metric-name "RunFailures" \
--namespace "AWS/Omics" \
--statistic "Sum" \
--period 300 \
--threshold 1 \
--comparison-operator "GreaterThanOrEqualToThreshold" \
--alarm-actions "arn:aws:sns:ap-northeast-2:123456789012:genomics-alerts" \
--region ap-northeast-2
디버깅 체크리스트
1단계: 기본 정보 확인
# 실행 상태 확인
aws omics get-run --id <run-id> --region ap-northeast-2
# 워크플로우 정보 확인
aws omics get-workflow --id <workflow-id> --region ap-northeast-2
2단계: 실패 태스크 식별
# 실패한 태스크 목록
aws omics list-run-tasks --id <run-id> --status FAILED --region ap-northeast-2
# 특정 태스크 상세 정보
aws omics get-run-task --id <run-id> --task-id <task-id> --region ap-northeast-2
3단계: 로그 분석
# 엔진 로그 확인
aws logs get-log-events \
--log-group-name /aws/omics/WorkflowLog \
--log-stream-name run/<run-id>/engine \
--region ap-northeast-2
# 태스크 로그 확인
aws logs get-log-events \
--log-group-name /aws/omics/WorkflowLog \
--log-stream-name run/<run-id>/task/<task-id> \
--region ap-northeast-2
4단계: 로컬 재현 테스트
# miniWDL로 로컬 테스트
miniwdl run -i debug_inputs.json -d debug_output task.wdl
# 소규모 데이터로 테스트
miniwdl run -i small_test_inputs.json workflow.wdl
7. 비용 최적화 실전 가이드
예상치 못한 비용 증가 원인
1. 실패 후 재시도로 인한 중복 비용
원인: 워크플로우 실패 → 전체 재실행 → 성공한 태스크도 다시 실행
해결: Call cache 활용 또는 체크포인트 기반 재시작
2. 과도한 리소스 할당
문제: 모든 태스크에 최대 리소스 할당
해결: 태스크별 동적 리소스 할당
3. DYNAMIC 스토리지 장기간 사용
문제: 반복 워크로드에서 DYNAMIC 스토리지 계속 사용
해결: 사용 패턴 분석 후 STATIC 전환
비용 모니터링 자동화
일일 비용 리포트:
#!/bin/bash
# daily_cost_report.sh
DATE=$(date -d "yesterday" +%Y-%m-%d)
aws ce get-cost-and-usage \
--time-period Start=${DATE},End=$(date +%Y-%m-%d) \
--granularity DAILY \
--metrics BlendedCost \
--group-by Type=DIMENSION,Key=SERVICE \
--filter file://omics-filter.json \
--region us-east-1
omics-filter.json:
{
"Dimensions": {
"Key": "SERVICE",
"Values": ["Amazon Omics"]
}
}
비용 최적화 체크리스트
- DYNAMIC → STATIC 스토리지 전환 검토
- 태스크별 리소스 요구사항 최적화
- 실패한 워크플로우 재시작 전략 수립
- 개발/테스트 환경 분리
- 데이터 라이프사이클 정책 적용
- 스팟 인스턴스 활용 (AWS Batch 환경)
8. 프로덕션 배포 체크리스트
배포 전 검증
기술적 검증:
- miniWDL 로컬 테스트 완료
- 소규모 데이터셋으로 HealthOmics 테스트 완료
- ECR 권한 설정 완료
- WDL 호환성 검증 완료
- 리소스 요구사항 최적화 완료
운영적 검증:
- 모니터링 대시보드 구성 완료
- 알림 설정 완료
- 비용 예산 및 알림 설정 완료
- 백업 및 복구 절차 수립 완료
- 사용자 교육 완료
보안 검증:
- IAM 역할 및 정책 검토 완료
- 데이터 암호화 설정 완료
- 네트워크 보안 설정 완료
- 감사 로깅 활성화 완료
단계적 배포 전략
Phase 1: 파일럿 테스트 (1-2주)
목표: 단일 워크플로우, 소규모 데이터
범위: 1-2개 샘플, 핵심 사용자 그룹
성공 기준: 95% 성공률, 예상 비용 내 완료
Phase 2: 제한적 배포 (2-4주)
목표: 전체 파이프라인, 중간 규모 데이터
범위: 10-20개 샘플, 확장된 사용자 그룹
성공 기준: 성능 목표 달성, 사용자 만족도 4.0+
Phase 3: 전체 배포 (4-8주)
목표: 프로덕션 워크로드, 전체 사용자
범위: 100+ 샘플/월, 모든 사용자
성공 기준: SLA 달성, 비용 목표 달성
9. 장애 대응 플레이북
일반적인 장애 시나리오
시나리오 1: 워크플로우 실행 실패
1. 실행 상태 확인
aws omics get-run --id <run-id>
2. 실패 원인 분류
- ECR 권한 문제 → ECR 정책 확인
- 리소스 부족 → 리소스 요구사항 증가
- WDL 호환성 → 로컬 테스트 수행
3. 해결 후 재시작
- 동일 입력으로 새 실행 시작
- 모니터링 강화
시나리오 2: 비용 급증
1. 비용 분석
aws ce get-cost-and-usage --time-period Start=2025-01-01,End=2025-01-08
2. 원인 파악
- 실패 후 재시도 → 체크포인트 재시작
- 과도한 리소스 → 리소스 최적화
- 장기간 실행 → 타임아웃 설정
3. 즉시 조치
- 불필요한 실행 중단
- 예산 알림 임계값 조정
시나리오 3: 성능 저하
1. 메트릭 확인
- CloudWatch 대시보드 점검
- 리소스 사용률 분석
2. 병목 지점 식별
- I/O 집약적 태스크 → 스토리지 최적화
- CPU 집약적 태스크 → 인스턴스 타입 변경
- 메모리 부족 → 메모리 증가
3. 최적화 적용
- 리소스 요구사항 조정
- 병렬 처리 최적화
에스컬레이션 매트릭스
| 심각도 | 대응 시간 | 담당자 | 에스컬레이션 |
|---|---|---|---|
| P1 (Critical) | 15분 | 운영팀 | 1시간 후 관리자 |
| P2 (High) | 1시간 | 운영팀 | 4시간 후 관리자 |
| P3 (Medium) | 4시간 | 개발팀 | 1일 후 관리자 |
| P4 (Low) | 1일 | 개발팀 | 3일 후 관리자 |
10. 성능 벤치마킹 및 최적화
실제 성능 데이터
HG002 샘플 기준 (177.4GB 입력 데이터):
HealthOmics 실행 결과:
- Data Processing QC: 3.2시간
- Assembly (Hifiasm): 28시간
- Polishing: 14시간
- Total QC: 6시간
- 총 실행 시간: 51.2시간
- 총 비용: $243
최적화 후 예상 성능:
- STATIC 스토리지: 20% 성능 향상
- GPU 활용: DeepPolisher 4-10x 향상
- 리소스 최적화: 15% 비용 절감
성능 최적화 우선순위
1순위: 메모리 집약적 태스크
Hifiasm Assembly:
- 현재: 512GB 메모리, 64 CPU
- 최적화: 동적 할당 (256-512GB)
- 효과: 25% 비용 절감
2순위: I/O 집약적 태스크
Data Processing:
- 현재: DYNAMIC 스토리지
- 최적화: STATIC 스토리지
- 효과: 20% 성능 향상
3순위: GPU 가속 가능 태스크
DeepPolisher:
- 현재: CPU only (12-24시간)
- 최적화: GPU 활용 (2-6시간)
- 효과: 4-10x 성능 향상
결론
본 가이드는 HPP Production Workflows를 AWS HealthOmics에서 성공적으로 운영하기 위한 실전 경험을 바탕으로 작성되었습니다.
핵심 교훈:
- 사전 검증의 중요성: miniWDL 로컬 테스트로 대부분의 문제 사전 발견 가능
- 점진적 접근: 소규모 테스트 → 단계적 확장으로 위험 최소화
- 모니터링 필수: 실시간 모니터링과 알림으로 신속한 문제 대응
- 비용 관리: 지속적인 최적화로 예측 가능한 비용 구조 달성
다음 단계:
- 정기적인 성능 리뷰 및 최적화
- 새로운 AWS 서비스 평가 및 도입
- 커뮤니티 모범 사례 공유 및 학습
문서 버전: 1.0
최종 업데이트: 2025-01-08
작성자: Kiro AI Assistant
기반 데이터: 실제 프로덕션 환경 트러블슈팅 사례
No comments to display
No comments to display