파이썬 파일입출력 고급 기법 NDJSON 스트리밍 파서 설계와 실패 행 격리

🔎 NDJSON이란 무엇인가

NDJSON(Newline Delimited JSON)은 이름 그대로 한 줄마다 하나의 JSON 객체를 기록하는 방식입니다.
일반 JSON은 하나의 거대한 트리 구조를 가지기 때문에, 수백 MB 이상의 대용량 파일을 한 번에 메모리에 로드하면 성능 문제가 발생할 수 있습니다.
반면 NDJSON은 각 줄을 독립된 JSON 객체로 취급하기 때문에, 스트리밍 처리와 라인 단위 파싱이 가능하다는 장점이 있습니다.

이 포맷은 빅데이터 환경에서 특히 많이 사용됩니다.
예를 들어 서버 로그, 이벤트 스트림, 센서 데이터 등은 모두 시간이 흐르면서 계속 추가되는 데이터인데, 이때 NDJSON 구조가 이상적입니다.
라인 단위로 읽고 쓸 수 있기 때문에 메모리 부담 없이 순차적으로 처리할 수 있고, 실시간 분석 파이프라인과도 잘 맞아떨어집니다.

• 📄일반 JSON: 전체 구조를 하나의 트리로 저장
• 🔎NDJSON: 한 줄마다 독립적인 JSON 객체
• ⚡스트리밍 처리 및 실시간 로그 분석에 최적화

실제로 NDJSON은 엘라스틱서치(Elasticsearch) 같은 검색 엔진, 아파치 로그 수집기(Logstash), 데이터 파이프라인 툴에서 기본적으로 지원하는 형식입니다.
즉, 데이터 분석과 머신러닝 학습에 활용되는 데이터셋을 교환할 때도 자주 등장하는 표준 포맷이라 할 수 있습니다.

💬 한 문장으로 요약하면, NDJSON은 대용량 데이터를 ‘끊김 없이’ 저장하면서도 ‘한 줄씩 안전하게’ 처리할 수 있는 JSON의 실용적 변형입니다.

⚡ 스트리밍 기반 파서 설계 원리

NDJSON은 한 줄이 하나의 JSON 객체라는 단순한 구조 덕분에 스트리밍 방식의 처리와 궁합이 좋습니다.
즉, 파일을 통째로 메모리에 불러오는 대신 한 줄씩 읽으면서 즉시 파싱하고 가공할 수 있다는 의미죠.
이 방식은 특히 수 GB 이상의 로그 파일이나, 끝없이 추가되는 실시간 데이터 스트림을 처리할 때 매우 유용합니다.

스트리밍 기반 파서를 설계할 때 핵심은 효율성과 안정성입니다.
효율성은 CPU와 메모리를 과도하게 소모하지 않고 끊임없이 데이터를 처리할 수 있어야 한다는 것이고, 안정성은 데이터 오류가 발생했을 때 전체 파이프라인이 멈추지 않고 정상 라인은 그대로 유지하는 능력을 말합니다.

🛠️ 스트리밍 설계의 기본 구조

기본적인 스트리밍 파서는 아래와 같은 구조를 따릅니다.

• 📥파일 또는 스트림에서 한 줄씩 읽어오기
• 🔎JSON 파싱 시도 및 유효성 검증
• ✅정상 객체는 즉시 처리(저장, 분석 등)
• 🚫파싱 실패 시 별도 오류 핸들링으로 분리

📊 이벤트 스트림과 NDJSON

Kafka, Flink, Spark Streaming 같은 분산 스트리밍 플랫폼에서도 NDJSON은 자주 활용됩니다.
각 메시지가 독립적인 JSON 객체라면 네트워크 전송과 저장이 간단해지고, 병렬 처리가 가능해지기 때문입니다.
즉, NDJSON은 단순한 파일 저장 형식을 넘어 실시간 데이터 처리의 핵심 포맷이라 할 수 있습니다.

🧩 파이썬으로 NDJSON 처리하기

파이썬은 NDJSON을 처리하기에 매우 적합한 언어입니다.
파일을 한 줄씩 읽어 json.loads()로 변환하기만 해도 간단히 파서를 구현할 수 있습니다.
특히 제너레이터(generator)를 사용하면 대용량 파일도 효율적으로 스트리밍 처리할 수 있습니다.

📜 기본 NDJSON 파싱 예제

import json

def ndjson_reader(file_path):
    with open(file_path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            try:
                yield json.loads(line)
            except json.JSONDecodeError:
                yield None  # 실패한 라인은 None 반환

위 코드에서는 각 줄을 JSON 객체로 변환하는 동시에, 파싱 오류가 발생하면 None을 반환하여 추후 격리 처리가 가능하게 합니다.
즉, 성공한 라인과 실패한 라인을 구분해 관리할 수 있습니다.

🧮 외부 라이브러리 활용

기본 json 모듈만으로도 처리가 가능하지만, orjson 같은 고성능 라이브러리를 사용하면 파싱 속도를 크게 높일 수 있습니다.
또한 pandas에서는 read_json(..., lines=True) 옵션을 제공하여 NDJSON 파일을 곧바로 데이터프레임으로 불러올 수 있습니다.

• ⚡기본 json 모듈로 직접 파서 구현
• 🚀orjson으로 빠른 파싱 성능 확보
• 📊pandas로 바로 데이터 분석 가능

🚫 실패 행 격리와 오류 로그 관리

NDJSON 스트리밍 파서를 설계할 때 가장 중요한 부분 중 하나는 실패 행 격리(failed line isolation)입니다.
데이터가 수십만~수백만 라인에 달할 경우, 단 하나의 잘못된 JSON 객체 때문에 전체 처리가 중단되는 것은 치명적인 문제를 일으킬 수 있습니다.
따라서 오류가 발생한 라인만 별도로 저장하고, 정상 데이터 처리는 이어지도록 설계하는 것이 필수적입니다.

📂 실패 행 저장 전략

실패 행은 단순히 무시하기보다는 별도의 로그 파일이나 DB 테이블에 기록해 두는 것이 좋습니다.
이때 각 실패 행에는 라인 번호, 실패 원인, 원본 데이터를 함께 저장하면 추후 재처리와 원인 분석에 유리합니다.

import json

def process_ndjson(path, error_log="errors.log"):
    with open(path, "r", encoding="utf-8") as f, open(error_log, "w", encoding="utf-8") as err:
        for i, line in enumerate(f, 1):
            try:
                record = json.loads(line)
                # 정상 데이터 처리
            except json.JSONDecodeError as e:
                err.write(f"{i}\t{e}\t{line}")

이처럼 실패한 행을 따로 기록하면 전체 파이프라인이 멈추지 않고, 정상 데이터만 먼저 활용할 수 있습니다.
이후 문제가 된 행만 따로 재검토하거나 클린징 과정을 거치면 됩니다.

⚠️ 오류 처리에서 주의할 점

실무에서는 오류 로그를 ELK(Elasticsearch, Logstash, Kibana) 스택이나 데이터 품질 대시보드로 모니터링하는 경우도 많습니다.
이렇게 하면 전체 데이터 파이프라인의 신뢰성을 크게 높일 수 있습니다.

💡 대용량 데이터 활용 사례

NDJSON과 스트리밍 파서는 단순한 이론이 아니라 실제 대규모 데이터 환경에서 널리 사용되고 있습니다.
실패 행 격리까지 고려한 설계를 적용하면 안정성과 확장성을 동시에 확보할 수 있습니다.
대표적으로 로그 분석, 머신러닝 데이터 전처리, IoT 데이터 수집 같은 분야에서 강력한 효과를 발휘합니다.

📊 로그 분석 및 보안 모니터링

대기업 IT 시스템에서는 하루에도 수십 GB의 로그가 생성됩니다.
NDJSON은 이런 로그를 라인 단위로 바로 수집하고 분석할 수 있어 보안 이상 징후 탐지나 실시간 운영 모니터링에 필수적으로 활용됩니다.

🤖 머신러닝 데이터셋 준비

머신러닝 학습용 데이터셋은 대개 수백만 건의 이벤트로 이루어집니다.
NDJSON은 각 이벤트를 독립적으로 기록하기 때문에 샘플링, 전처리, 병렬 처리가 용이합니다.
따라서 TensorFlow나 PyTorch 같은 프레임워크로 데이터를 공급할 때도 유리합니다.

📡 IoT 및 센서 데이터

스마트 팩토리, 자율주행 차량, 환경 모니터링 시스템 등에서 발생하는 IoT 데이터는 초당 수천 건에 달할 수 있습니다.
이 데이터를 효율적으로 다루기 위해 NDJSON 포맷을 이용하면, 장치에서 발생하는 이벤트를 스트리밍 방식으로 서버에 전달하고 곧바로 저장·분석할 수 있습니다.

이처럼 NDJSON은 단순한 데이터 저장 형식을 넘어서 다양한 산업 현장에서 핵심 기술로 자리 잡고 있습니다.
데이터 파이프라인의 신뢰성과 성능을 동시에 확보할 수 있다는 점에서, 앞으로도 활용 범위는 더욱 넓어질 것입니다.

❓ 자주 묻는 질문 (FAQ)