우분투 실전 명령어 | jq로 JSON 로그 빠르게 필터링하기

Last updated on 

서버 로그나 API 응답이 JSON으로 떨어질 때, grep만으로는 필요한 필드를 정확히 뽑기 어렵습니다. 이럴 때 jq를 쓰면 조건 필터, 필드 추출, 집계를 한 번에 처리할 수 있습니다.

언제 쓰는가

  • 애플리케이션 로그가 JSON Lines 형식일 때
  • curl 응답에서 특정 필드만 빠르게 확인해야 할 때
  • 장애 분석 중 에러 레벨 로그만 추려서 볼 때
  • 운영 리포트용으로 상태 코드/유저/시간대별 건수를 셀 때

바로 쓰는 명령어

# jq 설치(우분투)
sudo apt update && sudo apt install -y jq

# JSON 응답 보기 좋게 정렬 출력
curl -s https://api.github.com/repos/torvalds/linux | jq .

# JSON Lines 로그에서 error 레벨만 추출
jq -r 'select(.level=="error") | [.ts, .service, .msg] | @tsv' app.log

# 상태 코드별 개수 집계
jq -r '.status' access.jsonl | sort | uniq -c | sort -nr

핵심 옵션/패턴

  • jq -r: 문자열 따옴표를 제거한 raw 출력으로 파이프 후처리에 유리
  • select(조건): 필요한 레코드만 필터링
  • .field?.subfield?: 키가 없을 수 있는 데이터에서 안전 접근
  • map, group_by, length: 배열 데이터 요약/집계
  • @tsv, @csv: 표 형태로 내보내 엑셀/리포트 연계에 편리

명령 출력 예시

$ jq -r 'select(.level=="error") | [.ts, .service, .msg] | @tsv' app.log
2026-02-18T21:05:11Z	billing	payment timeout
2026-02-18T21:08:44Z	auth	jwt verify failed

$ jq -r '.status' access.jsonl | sort | uniq -c | sort -nr
120 200
 17 500
  9 404

자주 하는 실수

  • jq 없이 grep으로 JSON을 파싱해서 키 순서 변경에 깨지는 경우
  • JSON 배열과 JSON Lines를 같은 입력 형식으로 가정하는 경우
  • 숫자 비교를 문자열 비교로 작성해 필터 결과가 달라지는 경우
  • -r 없이 출력해 따옴표가 포함된 채로 다음 명령에서 실패하는 경우

검증 방법

# 입력 파일이 유효한 JSON인지 먼저 확인
jq . sample.json > /dev/null && echo "valid"

# JSON Lines 파일 각 줄 검증
cat app.log | jq -c . > /dev/null && echo "jsonl valid"

# 필터 결과 건수 확인
jq -c 'select(.level=="error")' app.log | wc -l

# 집계 결과 상위 5개 확인
jq -r '.status' access.jsonl | sort | uniq -c | sort -nr | head -5

운영 팁

  • 운영 서버에는 alias로 jq 기본 포맷을 만들어 두면 반복 작업이 빨라집니다.
  • 샘플 100줄로 먼저 필터를 검증한 뒤 전체 로그에 적용하면 실수 비용이 줄어듭니다.
  • 민감정보가 포함될 수 있으니 추출 전에 토큰, 이메일, 전화번호 마스킹 규칙을 같이 두세요.

출처

  • jq 공식 문서
  • Ubuntu Manpage
  • RFC 8259