Apache POI 기반 에러 리포팅 기능 개발

1. 개요 및 추진 배경

대형병원 차세대 구축 프로젝트의 테스트 단계에서는 하루 수만 건 이상의 로그가 지속적으로 발생하였습니다. 테스트 과정에서 발생하는 장애를 빠르게 파악하고 품질을 검증하기 위해서는 매일 로그를 직접 확인하며 에러 유형을 분류하고 정리하는 작업이 필수적이었습니다.

당시 기준으로 에러 리포트를 수기로 작성하는 데 하루 평균 약 1시간 이상이 소요되었으며, 로그량이 많은 날에는 그 이상이 걸리기도 했습니다. 또한 수작업 특성상 누락이나 오분류 가능성도 존재했습니다.

이에 따라 다음과 같은 목표를 가진 자동화 시스템을 직접 기획하고 개발하였습니다.

• 반복적인 수작업 제거

• 대량 로그를 안정적으로 처리 가능한 리포팅 시스템 구축

• 누구나 동일한 형태의 리포트를 즉시 생성 가능하도록 API 제공

• 향후 추가 분석 요구사항에도 유연하게 대응 가능한 구조 설계

결과적으로 Apache POI 기반의 엑셀 리포팅 자동화 API를 구축하여, 기존 수작업 기반의 로그 분석 프로세스를 완전히 자동화할 수 있었습니다.

2. Apache POI 도입 배경 및 기술 선정 과정

2-1. 리포팅 형식 선정 배경

초기에는 단순 JSON 응답 형태로 데이터를 제공하는 방안도 고려했습니다.
하지만 실제 테스트 실무에서는 대부분의 인력이 엑셀 기반으로 데이터를 검토하고 있었으며, 다음과 같은 이유로 엑셀 형식이 가장 적합하다고 판단했습니다.

• 테스트 담당자 및 현업 사용자가 가장 익숙하게 사용하는 포맷

• 정렬, 필터, 조건 검색 등이 매우 용이함>

• 추가 분석 및 2차 가공이 쉬움

• 메일 첨부 및 공유가 편리하고, 운영 보고 자료로도 바로 활용 가능함

특히 단순히 “로그를 조회한다” 수준이 아니라,
실제 운영과 테스트 현장에서 바로 사용할 수 있는 결과물을 만드는 것이 중요하다고 판단했습니다.

이에 따라 최종 결과물 포맷을 엑셀(.xlsx) 기반으로 결정하게 되었습니다.

2-2. Apache POI 선정 이유

엑셀 생성 라이브러리를 선정하는 과정에서 여러 방안을 검토했습니다.

그 과정에서 가장 중요하게 고려했던 요소는 다음과 같았습니다.

1) 대용량 데이터 처리 안정성

하루 수만 건 이상의 로그 데이터를 처리해야 했기 때문에 메모리 안정성이 가장 중요한 요소였습니다. 일반적인 엑셀 라이브러리들은 모든 데이터를 메모리에 적재한 뒤 파일을 생성하는 방식이 많았고, 이는 대량 데이터 환경에서 Out Of Memory(OOM) 위험이 존재했습니다.

Apache POI는 SXSSF(Stream 방식)를 지원하여 일부 데이터만 메모리에 유지하면서 파일을 생성할 수 있었고, 대용량 처리에 매우 적합했습니다.>

2) Java 생태계와의 높은 호환성

프로젝트의 전체 백엔드가 Java + Spring 기반으로 구성되어 있었기 때문에, Java 환경과 자연스럽게 통합 가능한 라이브러리가 필요했습니다.

Apache POI는 Java 표준 생태계에서 가장 널리 사용되는 엑셀 처리 라이브러리였으며,

• 유지보수 레퍼런스가 풍부하고

• 문서화가 잘 되어 있으며

• 커뮤니티 사례가 많고

• 안정성이 검증되어 있다는 점이 장점이었습니다.

특히 차세대 프로젝트 특성상 여러 개발자가 함께 유지보수해야 했기 때문에, 특정 개인만 이해할 수 있는 기술보다 범용성과 표준성이 높은 라이브러리를 사용하는 것이 중요했습니다.

3-1. 수집된 로그 데이터를 Apache POI 기반 엑셀로 생성

먼저 로그 중앙화 시스템인 Loki API를 통해 특정 기간 동안 발생한 로그 데이터를 구조화된 객체로 변환한 후, Apache POI를 사용하여 엑셀 리포트를 생성했습니다.

리포트는 다음과 같은 형태로 구성했습니다.

• 서비스별 에러 현황 시트

• 에러 코드 통계 시트

• 상세 에러 로그 시트

• 시간대별 발생 현황

각 시트는 동적으로 생성되도록 구현하였으며,
테스트 대상 서비스가 변경되어도 별도 수정 없이 대응 가능하도록 설계했습니다.

3-2. SXSSF 적용 및 메모리 최적화

초기에는 일반적인 XSSFWorkbook 방식으로 구현을 시도했습니다.

하지만 수만 건 이상의 로그 데이터를 처리하는 과정에서 메모리 사용량이 급격히 증가하였고, 실제로 OOM 위험이 발생했습니다.

이를 해결하기 위해 Apache POI의 SXSSFWorkbook 방식을 적용했습니다.

SXSSF는 다음과 같은 특징을 가집니다.

• 일정 Row 개수만 메모리에 유지

• 초과 데이터는 디스크 임시 파일로 flush

• Streaming 방식으로 대용량 파일 생성 가능

이를 통해 메모리 사용량을 안정적으로 유지하면서도 대량 로그를 안전하게 처리할 수 있었습니다.

다만 SXSSF에는 다음과 같은 제약도 존재했습니다.

• flush된 Row는 이후 수정이 불가능

• 데이터는 순차적으로만 작성 가능

• 이전 Row 접근에 제한 존재

따라서 구현 시에는 다음과 같은 점들을 고려했습니다.

• 헤더/스타일을 먼저 정의

• 데이터 작성 순서를 사전에 설계

• 후처리가 필요한 로직 제거

• Sheet 구조를 사전에 확정

이러한 제약을 이해하고 설계 단계에서 반영한 것이 안정적인 구현에 큰 도움이 되었습니다.

4. 결론

해당 기능 개발을 통해, 하루 약 1시간 이상 소요되던 수기 작업을 약 3초로 단축할 수 있었으며, 단순 건수 확인 수준에 머물렀던 리포팅도 상세한 장애 분석이 가능한 수준으로 발전할 수 있었습니다.

이번 경험을 통해 단순히 “기능이 동작하는 코드”를 만드는 것보다, 운영 환경에서 발생할 수 있는 데이터 규모와 유지보수성, 확장성까지 함께 고려하는 것이 백엔드 엔지니어에게 매우 중요하다는 점을 체감할 수 있었습니다.

앞으로도 단순 구현을 넘어, 실제 현장의 문제를 해결하고 운영 효율을 높일 수 있는 구조를 고민하는 개발자로 성장해 나가고자 합니다

Novin

참고 문헌

https://poi.apache.org/