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