디버깅
파이프라인 실행 중 발생하는 문제를 분석하고 해결하기 위한 도구와 방법을 설명합니다. 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 순서로 범위를 좁혀가며 분석합니다.
- 단계적 테스트: 복잡한 파이프라인은 노드를 하나씩 추가하며 각 단계를 검증합니다.
- 작은 데이터로 테스트: 전체 데이터 실행 전 소량의 샘플 데이터로 먼저 테스트합니다.
- 이전 성공 배치 비교: 실패한 배치와 이전 성공 배치의 입력 데이터, 설정 차이를 비교합니다.