NiFi 2.2.0 에 ListFile 프로세스

ListFile Processor란?

NiFi의 디렉토리 감시 Processor로,
특정 폴더의 파일 목록을 주기적으로 스캔하고, 새로 발견된 파일 이름을 FlowFile로 내보내는 역할을 합니다.

❗중요:
ListFile은 파일을 직접 읽는 게 아니라 "파일 목록만" 나열합니다.
파일 내용을 읽으려면 → FetchFile Processor와 연결해야 합니다.

---

✅ 대표적인 용도

용도설명

폴더에 새로 생성된 파일 자동 감지	정해진 주기로 폴더 스캔
파일이름을 FlowFile로 넘김	이후 FetchFile이 내용을 읽음
대용량 디렉토리 분할 처리	많은 파일을 하나씩 순차 처리 가능
파일 메타정보 기준 조건 분기	사이즈, 수정 시간 등으로 필터링

 

---

⚙️ 주요 설정 (NiFi 2.2.0 기준)

속성명설명예시

Directory	감시할 대상 디렉토리	/data/incoming
File Filter Regex	포함할 파일명 패턴 (정규표현식)	.*\.csv, data_.*\.json
Ignore Hidden Files	숨김파일 무시 여부	true 권장
Minimum File Age	최소 파일 나이 (안정화 목적)	1 min → 쓰기 완료된 파일만 처리
Maximum File Age	최대 파일 나이	7 days 등
Minimum File Size	최소 크기 필터	1 KB
Maximum File Size	최대 크기 필터	10 MB
Batch Size	한번에 최대 탐색할 파일 수	기본 100
Record Writer	(2.2.0 신기능) → FlowFile에 메타데이터를 JSON 등으로 기록 가능	JsonRecordSetWriter

 

---

🔁 내부 동작 방식

1. ListFile이 주기적으로 디렉토리를 스캔
2. 새로운 파일이 발견되면 → FlowFile로 생성 (내용 없음)
3. 파일의 메타데이터 (경로, 이름, 크기 등) 를 속성(attribute) 으로 포함
4. 다음 Processor (FetchFile)에서 실제 파일 내용을 읽음

---

📄 생성되는 FlowFile 속성 예시

속성값 예시

filename	sample.csv
path	/data/incoming/
absolute.path	/data/incoming/sample.csv
file.size	10240
file.lastModifiedTime	2025-05-14T09:22:00+0900

 

---

🔧 실전 활용 흐름

plaintext

CopyEdit

[ListFile] (파일 목록 나열) ↓ [FetchFile] (실제 파일 읽기) ↓ [UpdateAttribute / ReplaceText] (전처리) ↓ [PutFile / PutElasticsearchHttp] (저장 또는 전송)

---

🧠 팁: ListFile은 Stateful Processor

• 내부에 "상태(State)"를 저장해서, 이미 처리한 파일은 다시 안 봄
• Processor 중단 후 재시작해도 중복 안 됨
• 클러스터 모드에서는 Primary Node에서만 실행되어야 함

---

⚠️ 주의사항

항목설명

대용량 디렉토리	수천 개 이상 파일이 있을 경우 성능 영향 가능
파일 변경 중 감지 방지	Minimum File Age = 1 min 이상 설정 권장
로그 확인 필요	nifi-app.log에서 파일 탐색 관련 오류 확인 가능
파일 이동/삭제는 안함	실제 파일을 처리하려면 FetchFile 필요

 

---

✅ 요약

항목설명

역할	지정한 폴더의 파일들을 리스트 업 (내용은 읽지 않음)
출력	각 파일에 대한 FlowFile (속성에 메타정보 포함)
사용법	ListFile → FetchFile 연결 필수
클러스터	Primary Node에서만 실행 권장
활용	폴더 기반 데이터 수집의 시작점

🔍 Listing Strategy란?

🔧 파일 목록 추적 방법(= 상태 관리 방식)을 선택하는 옵션입니다.

즉, ListFile이 어떤 기준으로 **"이 파일은 처음 보는 파일이야"**라고 판단할지를 결정합니다.

---

✅ 주요 옵션 (NiFi 2.2.0 기준)

값의미설명

Tracking Timestamps	시간 기반 추적 (기본값)	마지막 수정 시각이 최신인 파일만 선택함
Tracking Entities	파일 고유 정보 추적	파일 이름, 크기, 수정 시간 등 파일 상태를 종합 비교함

 

---

🧠 비교 요약

항목Tracking TimestampsTracking Entities

기준	마지막 수정 시간 (lastModifiedTime)	파일의 경로 + 이름 + 크기 + 수정 시각 조합
상태 저장	수정 시간만 저장	전체 파일 엔터티 정보 저장
장점	빠름, 간단	정확함, 중복/누락 방지
단점	같은 이름/경로의 파일이 재업로드되면 못 잡을 수도 있음	상태 저장량 많음, 약간 느릴 수 있음
추천 상황	파일 생성 순서가 확실하고 시간 기반이면	동일 경로에 파일이 덮어쓰이는 경우 (정확성이 중요할 때)

 

---

🎯 예시 상황

🔹 예제 1: 하루에 한 번씩 CSV 업로드 (파일 이름이 다름)

• 파일명: sales_20250514.csv, sales_20250515.csv …
• Tracking Timestamps 사용 가능 (기본값 OK)

🔹 예제 2: 같은 이름의 파일이 내용만 바뀌며 덮어쓰기됨

• 파일명: 항상 daily_report.csv
• 이 경우 Tracking Entities 사용이 더 안전함

---

⚠️ 상태(State) 저장 위치

NiFi는 Listing Strategy에 따라 파일 목록 상태를 로컬 또는 클러스터에 저장합니다:

• Standalone: conf/state/local 경로
• Cluster: ZooKeeper 기반으로 동기화

※ FlowFile ID가 아닌 파일 경로+정보를 별도로 추적합니다

---

✅ 요약 정리

항목설명

설정 위치	ListFile Processor → Properties 탭
이름	Listing Strategy
역할	어떤 방식으로 파일 처리 상태를 추적할지 설정
기본값	Tracking Timestamps
추천	파일명이나 경로가 변하지 않고 내용만 바뀌는 경우 → Tracking Entities