JSON Toolkit

jq로 다루는 대용량 JSON: -s가 메모리를 터뜨리는 이유와 스트리밍 작성법

핵심 요약: 수백 MB짜리 JSON 로그를 jq -s로 집계하면 시스템에 의해 종료되지만, reduce inputs로 바꾸면 같은 통계를 몇 MB의 메모리로 처리할 수 있습니다. 220MB, 200만 행 샘플로 두 방식의 실행 시간과 메모리 피크를 실측하고, -s와 전체 파싱이 메모리를 잡아먹는 메커니즘, JSONL 행 단위 처리의 정석, --stream 경로 이벤트, 그리고 -n --stream이 조용히 빈 출력으로 끝나는 함정 등 세 가지 실제 함정을 설명합니다.

심화약 6분 소요2026-11-12 발행2026-11-12 업데이트
jq 스트리밍 처리와 -s의 메모리 소비를 비교한 도해

jq 자체는 파싱이 빠릅니다. 그런데 수백 MB 파일에서 죽는 거의 모든 사례는 같은 작성법에서 비롯됩니다. -s는 입력 전체를 하나의 거대한 배열로 메모리에 올리며, 피크 RSS는 파일 크기의 몇 배에서 열 배까지 치솟습니다.

현상: 같은 파일, 작성법에 따라 메모리가 580배 차이

먼저 실측값부터 보겠습니다. 샘플은 220MB, 200만 행의 JSONL 로그(한 줄에 요청 레코드 하나, timestamp·level·path·status·duration_ms·uid 여섯 필드)입니다. 환경은 jq 1.7, Linux x86_64이며 피크 RSS는 /usr/bin/time -v로 측정했습니다.

작성법 작업 시간 피크 RSS
jq -s 'group_by(.level) | ...' level별 전량 집계 10.1s 2.08 GB(파일의 약 9.5배)
jq -n 'reduce inputs ...' 동일한 집계 4.7s 3.5 MB
jq -r 'select(...) | .path' 행 단위 필터 2.6s 3.6 MB

같은 통계 작업인데 작성법만 바꿔 메모리가 580분의 1로 줄고 시간까지 더 짧아집니다. 이것은 jq의 버그가 아닙니다. -s의 의미론은 애초에 "입력 전부를 하나의 값으로"이고, 대부분의 사람은 집계 코드를 쓸 때 이 기본 비용을 계산에 넣지 않을 뿐입니다. 제3자 데이터도 일치합니다. 화웨이클라우드 커뮤니티의 2.3GB JSONL 사례 기록에서는 -s로 OOM이 났고 스트리밍으로 바꾸자 47초 만에 RSS 30MB 남짓으로 끝났습니다. dratini.tech는 2.5GB 입력에서 jq -s가 16GB+ 메모리 장비에서도 OOM killer에게 종료되는 것을 측정했고, 일반 파이프라인은 48.2초, 84MB로 완주했습니다.

결론부터: 파일 크기가 가용 메모리의 절반을 넘으면 -s는 고려 대상에서 제외합니다. 손대기 전에 세 가지를 잽니다. ls -lh로 크기, free -m으로 가용 메모리, wc -l로 행 수입니다.

-s와 전체 파싱이 메모리를 잡아먹는 메커니즘

jq -s(slurp)의 공식 정의는 "모든 입력을 읽어 하나의 배열에 담는다"입니다. 실제 비용은 텍스트 자체보다 훨씬 큽니다. jq는 파싱 후 C 구조체로 이루어진 트리를 유지하며, 객체·배열·문자열·숫자 각각이 자신의 노드와 메타데이터를 가집니다. 220MB의 텍스트는 구조화되면 2GB 남짓이 되어 약 9.5배로 팽창합니다. group_by는 여기에 메모리상 정렬과 분류까지 더해 피크를 한층 올립니다.

단일 대형 JSON도 마찬가지입니다. 같은 로그를 jq -s '.'으로 300MB짜리 최상위 배열로 묶고 일반 필터 .[] | select(...)로 추출한 결과입니다.

작성법 시간 피크 RSS
jq '.[] | select(.level=="ERROR") | .uid'(전체 파싱) 4.7s 1.85 GB
jq --stream 'select(...)'(경로 이벤트 스트림) 13.4s 3.4 MB

전체 파싱도 피크는 1.8GB 규모입니다. jq는 트리 전체를 다 지어놓기 전에는 필터를 돌릴 수 없기 때문입니다. --stream은 약 3배의 시간을 지불하고 540배 작은 메모리를 얻습니다. 메모리가 어느 단계에서 팽창하는지의 자세한 모델은 메모리 점유의 원천에서 다룹니다.

JSONL 로그: 기본 행 단위 읽기가 정석

다루는 "대용량 파일"이 사실 한 줄에 객체 하나인 JSONL 로그라면 jq의 기본 동작은 이미 스트리밍입니다. 각 입력 행은 독립적으로 파싱되고 출력되며, -s는 불필요할뿐더러 해롭습니다.

# level별 건수 집계: 행 단위로 읽고 셸에서 집계
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# 필터 + 추출: select를 맨 앞에, 불일치 행은 즉시 폐기
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

의식적으로 몸에 붙일 세부가 두 가지 있습니다.

  • select는 파이프라인 맨 앞에. jq는 한 행을 파싱하자마자 필터링하므로, 변환 뒤에 두면 계산이 낭비됩니다.
  • -r로 날문자열 출력. -r이 없으면 출력이 따옴표 붙은 JSON 문자열이 되어, uniq -c는 "ERROR"와 ERROR를 서로 다른 값으로 셉니다.

깨진 행은 fromjson?으로 처리합니다. jq -r 'fromjson? | .level'처럼 쓰면 파싱 실패 행을 조용히 건너뛰어, 중간의 잘린 행이 파이프라인 전체를 끊지 않습니다. JSONL 형식 자체의 규칙은 JSONL 파일 실무에 맡기고 여기서는 처리 명령에 집중합니다.

전역 집계: reduce inputs로 상태를 유계로

행 단위 필터는 셸에 맡기면 충분하지만, level별 카운트나 path별 평균처럼 jq 내부에서 전역 집계를 끝내야 한다면 핵심은 reduce와 inputs로 상태를 고정 크기로 유지하는 것입니다.

# level별 카운트: 메모리는 결과 집합 크기에만 비례
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# path별 평균 소요시간: 상태는 {count, total} 두 필드
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

포인트는 두 가지입니다.

  • -n은 "첫 입력을 초기값으로 쓰지 마라"는 뜻으로, inputs가 전체 레코드를 하나씩 내보냅니다. -n을 빼먹으면 첫 레코드가 초기값으로 삼켜집니다.
  • 리듀서의 상태는 고정형이어야 합니다. 카운터와 누적값 같은 고정 필드만. 일치 행을 배열에 push하기 시작하면 메모리가 다시 데이터량에 비례해 스트리밍의 의미가 사라집니다.

앞 표의 3.5MB가 여기서 나옵니다. 2GB의 데이터가 흘러가도 남는 것은 해시테이블 하나입니다.

단일 대형 배열: --stream의 경로 이벤트

입력이 "하나의 거대한 최상위 문서"(수백 MB짜리 내보내기 파일처럼)여서 행 경계가 없다면 --stream을 씁니다. 완전한 값 대신 "경로 + 리프 값" 이벤트 열을 출력합니다.

# 이벤트는 경로 배열 + 스칼라 값의 형태
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

이벤트 스트림에서 추출하려면 경로 전체의 형상을 검사합니다. 깊이·멤버 이름·배열 인덱스 위치까지 확인해야 하며, 마지막 요소만 보는 필터는 중첩 객체 속의 동명 키까지 낚아챕니다.

# rows[i].id만 추출, meta.id와 깊은 곳의 동명 키는 무시
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

집계는 역시 고정형 reduce inputs입니다(-n --stream 조합에서는 inputs로 명시적으로 소비해야 하며, 다음 절의 함정 참조). 일치 이벤트를 완전한 객체로 재조립하려면 truncate_stream과 fromstream을 조합합니다. 파일 크기별 도구 선택의 전체 그림은 대용량 JSON을 열 수 없을 때에 있습니다.

실제로 밟은 세 가지 함정

함정 하나: -n --stream에 inputs가 없으면 조용히 빈 출력. 실측에서 밟았습니다. jq -n --stream 'select(...)' file.json은 종료 코드 0, 출력도 오류도 없습니다. -n 모드에서는 jq가 입력을 자동으로 읽지 않아 필터의 select에 이벤트가 하나도 전달되지 않기 때문입니다. 올바른 방법은 -n을 빼고 --stream, 혹은 -n --stream에 reduce inputs를 조합하는 것입니다. "성공했는데 비어 있음"류의 실패가 가장 디버깅이 어렵고, 파이프라인을 만들기 전에 작은 샘플로 출력을 확인해야 합니다.

함정 둘: --stream은 스칼라 리프만 내보냅니다. 빈 객체와 빈 배열에는 값 이벤트가 없습니다. {"a":{}}는 경로 종료 이벤트(length == 1)만 내고, length == 2만 검사하는 필터는 빈 컨테이너를 조용히 삼킵니다. 통계에 빈 컨테이너를 포함할지 명시적으로 결정해야 합니다.

함정 셋: 중간 parse error 후 부분 결과. 스트리밍 파이프라인은 앞부분을 이미 출력한 뒤 파일 끝의 깨진 JSON에서 실패할 수 있습니다. jq 1.7은 기본적으로 크게 실패합니다(실측: [1,]에서 parse error: Expected another array element at line 1, column 4, 종료 코드 5). 그러나 셸에서 stdout을 대상 파일로 리디렉션했다면 불완전한 파일이 이미 디스크에 있습니다. 공학적 해법은 staging + rename입니다. 임시 파일에 쓰고 jq 성공 후 mv로 교체합니다. 더 세밀한 제어는 --stream-errors로 파싱 오류를 이벤트화해 필터 안에서 명시적으로 error를 일으킵니다.

jq를 쓰지 말아야 할 때: Miller와 하이브리드

jq는 함수형 트리 변환 언어로 깊은 중첩 재구성에 강합니다. 그러나 작업이 "GB급 평면 로그의 필터와 통계"로 퇴화하면 더 맞는 도구가 있습니다. dratini.tech의 2.5GB JSONL 벤치마크(필터 + 열 선택)입니다.

도구 시간 피크 RSS
jq 일반 파이프라인 48.2s 84 MB
jq -s OOM(16GB+에서도 종료) —
Miller(mlr --json) 11.4s 18 MB
ripgrep + jq 하이브리드 8.1s 32 MB

선정 요령: 깊은 중첩·구조 변환·CI 보편성은 jq. 수 GB의 평면 JSONL 통계, p95 백분위, JSONL→TSV는 mlr --json stats1 한 줄이 jq 스크립트를 대체하고 메모리도 일정합니다. rg가 90%의 무관한 행을 먼저 걸러낼 수 있다면 하이브리드가 가장 빠릅니다.

자주 묻는 질문

jq -s는 어느 정도 파일부터 위험합니까?

경험적 기준은 파일이 가용 메모리의 절반을 넘을 때입니다. 파싱 후 메모리는 보통 텍스트의 3~10배(220MB 실측에서 9.5배, 제3자 기록에서는 4GB 파일이 16GB 장비를 OOM시킴). 먼저 ls -lh와 free -m을 비교하고 가까우면 -s를 reduce inputs로 교체합니다.

reduce inputs 앞에 왜 -n을 붙입니까?

-n은 "첫 입력을 프로그램의 초기값으로 삼지 마라"는 지시로, inputs가 전체 레코드를 스스로 내보내게 합니다. -n을 빼먹으면 첫 레코드가 reduce의 초기 상태로 사라져 결과에서 영원히 한 건이 빠집니다. 오류를 내지 않는 데이터 손실이라 아주 성가십니다.

jq --stream과 일반 모드는 어떻게 고릅니까?

먼저 파일 형태를 봅니다. JSONL은 행 단위로 이미 스트리밍이므로 --stream이 불필요합니다. 하나의 거대 문서에서 몇 개의 리프 값만 필요하다면 약 3배 시간으로 수백 배 메모리를 아끼는 --stream이 값어치가 있습니다. 메모리에 들어가는 파일이라면 일반 작성법이 더 빠릅니다.

스트리밍 중에 깨진 JSON 행을 만나면?

JSONL에서는 fromjson?으로 파싱 실패 행을 건너뛰어 한 줄의 오염이 파이프라인 전체를 끊지 않게 합니다. 단일 문서에서 중간 parse error는 실행을 실패시키므로 staging 파일과 rename으로 원자적 발행을 하고, 부분 결과가 대상 파일에 남지 않게 합니다. 세밀한 제어는 --stream-errors를 씁니다.