디버깅
파이프라인 실행 중 발생하는 문제를 분석하고 해결하기 위한 도구와 방법을 설명합니다. D.Hub은 파이프라인, 배치, 스텝 단위로 실행 이력을 기록하여 체계적인 디버깅을 지원합니다.
실행 이력 (Traces)
파이프라인이 실행될 때마다 상세한 실행 기록(Trace)이 자동으로 저장됩니다.
실행 이력 구조
실행 이력은 세 가지 계층으로 구성됩니다:
| 계층 | 설명 |
|---|---|
| Pipeline | 파이프라인 전체 실행 단위 |
| Batch | 파이프라인의 개별 실행 인스턴스 (실행할 때마다 새 배치 생성) |
| Step | 배치 내 각 노드의 실행 단위 |
실행 이력 조회
- 워크플로우 편집기 상단의 Run History Bar에서 특정 실행 건을 클릭합니다.
- 또는 파이프라인 목록에서 파이프라인을 선택하고 실행 이력 탭을 엽니다.
각 실행 건에서 확인할 수 있는 정보:
| 항목 | 설명 |
|---|---|
| 배치 ID | 실행 인스턴스의 고유 식별자 |
| 시작/종료 시간 | 실행 시작 및 완료 시각 |
| 소요 시간 | 전체 실행에 걸린 시간 |
| 상태 | 실행 결과 (SUCCESS, FAILED 등) |
| 트리거 | 실행 원인 (수동 실행, 스케줄, 이벤트) |
Batch 상태
각 배치는 다음 상태 중 하나를 가집니다:
| 상태 | 설명 | 후속 조치 |
|---|---|---|
| RUNNING | 현재 실행 중 | 완료 대기 또는 필요 시 Stop으로 중단 |
| SUCCESS | 모든 스텝이 성공적으로 완료 | 출력 데이터셋 확인 |
| FAILED | 하나 이상의 스텝에서 오류 발생 | 에러 분석 후 수정하여 재실행 |
| CANCELLED | 사용자에 의해 실행 취소 | 필요 시 재실행 |
에러 분석
스텝별 로그 확인
실행에 실패한 배치를 분석하는 단계:
- 실패한 배치 선택: Run History에서 빨간색(실패)으로 표시된 배치를 클릭합니다.
- 실패한 스텝 확인: 캔버스에서 빨간색 테두리로 표시된 노드를 확인합니다.
- Inspector 패널 확인: 실패한 노드를 클릭하여 Inspector 패널에서 에러 상세 정보를 확인합니다.
- History 탭 확인: Code 노드의 History 탭에서 배치 실행 이력과 상세 로그를 확인합니다.
에러 메시지 해석
Inspector 패널에서 확인할 수 있는 에러 정보:
| 항목 | 설명 |
|---|---|
| Error Type | 오류 유형 (ConnectionError, ValueError 등) |
| Error Message | 오류 원인을 설명하는 메시지 |
| Stack Trace | Python 코드의 상세 호출 스택 |
| Timestamp | 오류 발생 시각 |
일반적인 에러 유형과 해결 방법
| 에러 유형 | 원인 | 해결 방법 |
|---|---|---|
| ConnectionError | 데이터 소스(DB, API) 연결 실패 | 네트워크 상태, 인증 정보, 엔드포인트 주소 확인 |
| SchemaError | 입출력 데이터의 스키마 불일치 | 컬럼명, 데이터 타입 매핑 확인 |
| SyntaxError | Python/SQL 코드의 문법 오류 | 코드 문법을 수정하고 재실행 |
| RuntimeError | 코드 실행 중 예외 발생 | 스택 트레이스를 분석하여 로직 수정 |
| TimeoutError | 실행 시간 초과 | 쿼리 최적화, 데이터 크기 축소, 타임아웃 값 조정 |
| ResourceError | CPU/메모리 리소스 부족 | 리소스 제한 상향 또는 데이터 분할 처리 |
팁
Code 노드에서 오류가 반복되는 경우, 코드 내에 로깅(print 또는 logging)을 추가하여 중간 데이터 상태를 확인하면 원인을 더 빠르게 파악할 수 있습니다.
스텝별 상세 트레이스
각 스텝의 트레이스에서 다음 정보를 확인할 수 있습니다:
| 항목 | 설명 |
|---|---|
| 실행 시간 | 스텝 시작~종료 소요 시간 |
| 입력 레코드 수 | 스텝에 입력된 데이터 건수 |
| 출력 레코드 수 | 스텝에서 출력된 데이터 건수 |
| 로그 | 스텝 실행 중 출력된 로그 메시지 |
| 에러 | 발생한 에러의 상세 정보 |
배치 재실행
실패한 배치를 수정 후 다시 실행할 수 있습니다.
재실행 방법
- 실패 원인을 분석하고 코드 또는 설정을 수정합니다.
- 변경 사항을 Save합니다.
- 상단 툴바의 Run 버튼을 클릭하여 새 배치를 생성합니다.
경고
재실행 시 새로운 배치가 생성됩니다. 이전 실패한 배치의 이력은 보존되므로 비교 분석에 활용할 수 있습니다.
디버깅 모범 사례
- 로그 확인 순서: Pipeline → Batch → Step 순서로 범위를 좁혀가며 분석합니다.
- 단계적 테스트: 복잡한 파이프라인은 노드를 하나씩 추가하며 각 단계를 검증합니다.
- 작은 데이터로 테스트: 전체 데이터 실행 전 소량의 샘플 데이터로 먼저 테스트합니다.
- 이전 성공 배치 비교: 실패한 배치와 이전 성공 배치의 입력 데이터, 설정 차이를 비교합니다.