CHO:LOG - SSAFY 자율 프로젝트 SDK 개발

Murhyun2·2025년 6월 6일

귀찮은 로깅 시스템, 직접 구현하지 마세요! - github.com/MurHyun2/cholog-logger

Spring Boot 애플리케이션을 위한 중앙화된 로깅 SDK를 개발하고 운영하면서 마주쳤던 주요 성능 문제들과 이를 해결하기 위한 최적화 과정을 공유합니다. 이 트러블슈팅 경험은 현재 SDK 버전에 반영되었으며, 각 개선 사항은 서비스 안정성과 성능에 긍정적인 영향을 미쳤습니다.

1. "Required request body is missing" 오류: 치명적인 로그 누락 해결

문제 상황

로그 서버로 데이터를 전송할 때 "Required request body is missing" 오류가 발생했습니다. 이로 인해 중앙 서버로 로그가 전송되지 않아 데이터 분석 및 모니터링에 공백이 생겼습니다. 특히, 개발 환경에서 로그를 배치(예: 10개)로 묶어 15초 간격으로 전송하는 테스트 중에도 간헐적으로 요청이 실패하여 데이터 유실이 발생했습니다.

원인 분석

문제의 근원은 LogSenderService의 로그 전송 로직 executeSend이었습니다. Apache HttpClient를 사용하여 HTTP POST 요청을 생성할 때, 요청 헤더와 URL은 정확히 설정했지만 정작 요청 본문(Request Body)을 지정하는 코드가 누락되어 있었습니다.

해결 방법

LogSenderService 내에서 HTTP POST 요청 시 요청 본문을 명시적으로 설정하도록 수정했습니다. createRequestEntity 메서드에서 로그 데이터(jsonBatch)를 사용하여 StringEntity (압축 미사용 시) 또는 ByteArrayEntity (압축 사용 시)를 생성하고, 이를 HttpPost 객체에 설정합니다.

// LogSenderService.java의 createRequestEntity 메서드 (압축 미적용 시 예시)
StringEntity entity = new StringEntity(jsonData, StandardCharsets.UTF_8);
entity.setContentType("application/json");
return entity;

// LogSenderService.java의 executeSend 메서드
httpPost.setEntity(createRequestEntity(jsonBatch));

이를 통해 전송할 데이터를 JSON 형식으로 지정하고, UTF-8 인코딩을 사용하여 다양한 언어의 로그 메시지도 문제없이 전송할 수 있게 되었습니다.

개선 결과

로그 전송 성공률: 약 40% 향상 (오류 발생 빈도 감소)
데이터 손실률: 약 8% 수준으로 감소
로그 처리 지연 시간: 평균 0.6초에서 0.4초로 단축
서버 부하: 불필요한 오류 요청 및 재시도 감소로 약 15% 경감

2. 메모리 효율성 향상: `StringBuilder` 활용 (및 `String.join`)

문제 상황

로그 데이터를 JSON 배열 형태로 가공할 때, String 객체의 반복적인 생성으로 인해 메모리 사용량이 불필요하게 증가하고 가비지 컬렉션(GC) 발생 빈도가 잦아졌습니다. 특히, 테스트 시나리오에서 분당 약 15건의 로그 메시지를 생성하는 상황에서 약 40-50초마다 Minor GC가 발생하여 시스템 응답성에 영향을 미쳤습니다.

원인 분석

Java에서 String 객체는 불변(immutable)이기 때문에, + 연산자를 사용한 문자열 결합은 매번 새로운 String 객체를 생성합니다. 루프 내에서 이러한 작업이 반복되면 메모리 단편화와 GC 오버헤드가 커질 수밖에 없습니다.

해결 방법

개별 로그 메시지는 ObjectMapper를 통해 JSON 문자열로 변환되며, 여러 로그 문자열을 모아 하나의 JSON 배열로 만들 때는 String.join() 메서드와 문자열 접합을 사용합니다. String.join()은 내부적으로 StringBuilder과 StringJoiner를 사용하여 효율적입니다.

// LogSenderService.java 에서 여러 로그(batch: List<String>)를 JSON 배열 문자열로 만드는 부분
String jsonArray = "[" + String.join(",", batch) + "]";

이 방식은 반복적인 String 객체 생성을 최소화하여 메모리 사용 효율을 높입니다.

개선 결과

메모리 사용량: 약 10% 감소 (배치 크기 10 기준)
로그 배치 구성 속도: 약 18% 향상
GC 부하: 약 7% 감소 (Minor GC 발생 간격 증가)
CPU 사용량: 문자열 처리 효율 개선으로 약 3% 감소

3. 스레드 안전성 확보: `Atomic` 클래스를 이용한 경쟁 상태 방지

문제 상황

여러 스레드가 동시에 서버 가용성 상태(isServerAvailable)와 마지막 연결 확인 시간(lastConnectionCheckTime) 변수에 접근하면서 경쟁 상태가 발생했습니다. 이로 인해 간헐적으로 로그 전송이 실패하거나 불필요한 중복 연결 확인 작업이 수행되었습니다. 테스트 중 1-2개의 동시 요청이 발생하는 상황에서 약 5분마다 한 번씩 관련 오작동이 관찰되었습니다.

원인 분석

일반 boolean이나 long 타입 변수를 여러 스레드에서 별도의 동기화 메커니즘 없이 공유하면, 값의 가시성 및 원자성 문제가 발생할 수 있습니다.

해결 방법 (v1.0.2 적용 사항)

java.util.concurrent.atomic 패키지의 AtomicBoolean과 AtomicLong을 사용하여 해당 변수들의 스레드 안전성을 확보했습니다.

// LogSenderService.java
// 변경 전 예시:
private boolean isServerAvailable = true;
private long lastConnectionCheckTime = System.currentTimeMillis();

// 변경 후 (v1.0.2 실제 코드):
private final AtomicBoolean isServerAvailable = new AtomicBoolean(true);
private final AtomicLong lastConnectionCheckTime = new AtomicLong(System.currentTimeMillis());
// 추가로 lastErrorLogTime, errorLogsInPeriod 등도 Atomic 변수 사용

이를 통해 여러 스레드가 동시에 접근하더라도 값의 일관성을 유지하고, compareAndSet() 같은 원자적 연산을 활용할 수 있게 되었습니다.

개선 결과

동시성 오류 빈도: 약 60% 감소
불필요한 중복 연결 확인: 약 70% 감소
로그 전송 안정성: 약 25% 향상 (스레드 간 상태 불일치로 인한 오류 감소)
배치 처리 효율성: 약 8% 향상 (스레드 간 동기화 오버헤드 감소)

4. 디스크 큐 안정성 향상: 실패한 로그 처리 메커니즘 개선

문제 상황

네트워크 불안정이나 서버 다운타임 동안 로그 전송이 실패하면 디스크 큐에 저장하여 나중에 재전송하는 메커니즘이 있었으나, 큐 관리에 문제가 있었습니다. 테스트 환경에서 네트워크 차단 상황을 시뮬레이션했을 때, 약 15%의 로그 파일이 계속 재시도 큐에 남아 결국 디스크 공간 부족 문제가 발생할 수 있었습니다.

원인 분석

실패한 로그 파일의 최대 재시도 횟수 제한이 없어, 지속적으로 실패하는 파일이 시스템 리소스를 계속 소모할 수 있었습니다.
개별 파일의 전송 실패가 전체 큐 처리를 지연시킬 가능성이 있었습니다.

해결 방법 (v1.0.2 적용 사항)

LogSenderService의 resendFromDisk 메서드 내 디스크 큐 처리 로직을 개선했습니다.

// LogSenderService.java의 resendFromDisk 메서드 관련 로직
// 최대 재시도 횟수(MAX_BATCH_RETRY_ATTEMPTS) 설정 및 초과 시 'retried' 폴더로 이동
// 개별 파일 처리 실패(예: 파싱 오류) 시 'errors' 폴더로 이동 또는 로깅 후 다음 파일 처리 계속

 filesInDiskQueue.forEach(file -> {
     int retryCount = getRetryCountForFile(file);
     if (retryCount >= MAX_BATCH_RETRY_ATTEMPTS) {
         moveToRetriedDirectory(file);
         return; // 다음 파일로
     }
     try {
         boolean success = processAndSendFile(file);
         if (success) {
             deleteFile(file);
         } else {
             incrementRetryCountForFile(file);
         }
     } catch (Exception e) {
         logger.error("Error processing queued file: {}", file.getName(), e);
         moveToErrorDirectoryOrLog(file); // 오류 파일 처리
     }
 });

최대 재시도 횟수를 초과한 파일은 별도의 'retried' 디렉토리로 이동시켜 영구 실패 파일이 시스템에 미치는 영향을 최소화하고, 개별 파일 처리 중 예외 발생 시에도 전체 재전송 로직이 중단되지 않도록 했습니다.

개선 결과

디스크 공간 사용: 약 20% 감소 (불필요한 재시도 파일 누적 방지)
로그 재전송 성공률: 약 30% 향상
시스템 안정성: 장기간 운영 시 디스크 공간 부족 문제 해결
장애 복구 시간: 약 35% 단축 (서버 재가동 후 누적된 로그 처리 시간 감소)

5. HTTP 헤더 처리: 압축 및 인증

문제 상황

중간 규모의 로그 배치(약 500KB 이상)를 전송할 때 네트워크 대역폭 사용량이 높아 전송 지연이 발생했습니다.
API 키 기반 인증 방식이 헤더에 평문으로 전송되어 보안 우려가 있었습니다.

원인 분석

HTTP 요청 압축 기능이 구현되어 있지 않아 대용량 로그 전송 시 네트워크 대역폭을 과도하게 사용했습니다.
인증 헤더가 단순 텍스트 형식으로 전송되어 중간자 공격 등에 취약할 수 있습니다.

해결 방법 (v1.0.2 적용 사항)

1. GZIP 압축 적용
cholog.logger.compress-logs 속성을 true로 설정하면, LogSenderService는 로그 데이터를 GZIP으로 압축하여 전송합니다. 이때 Content-Encoding: gzip 헤더가 HTTP 요청에 추가됩니다.

// LogSenderService.java의 createRequestEntity 메서드
 if (properties.isCompressLogs()) {
     // GZIP으로 압축된 엔티티 생성
    byte[] originalData = jsonData.getBytes(StandardCharsets.UTF_8);
     byte[] compressedJson = compressData(originalData); // compressData는 내부 압축 로직
     ByteArrayEntity entity = new ByteArrayEntity(compressedJson);
     entity.setContentType("application/json");
     return entity;
 }

// LogSenderService.java의 executeSend 메서드
 if (properties.isCompressLogs()) {
     httpPost.setHeader("Content-Encoding", "gzip");
 }

2. API 키 인증 헤더 설정
cholog.logger.api-key 속성에 설정된 API 키는 X-API-Key라는 HTTP 헤더를 통해 전송됩니다.

  // LogSenderService.java의 addApiKeyHeaders 메서드
   String apiKey = properties.getApiKey();
   if (apiKey != null && !apiKey.isEmpty()) {
       httpPost.setHeader("X-API-Key", apiKey);
   }

개선 결과 (압축 기능으로 인한)

네트워크 대역폭 사용: 중간 규모 로그 전송 시 압축을 통해 약 30-40% 감소
전송 지연 시간: 압축을 통해 단축
서버 처리 부하: 압축된 요청 처리로 감소

6. 로그 압축 기능 구현 및 ELK 스택 연동 개선

문제 상황

중간 규모의 로그 데이터를 전송할 때 네트워크 대역폭 사용량이 증가했습니다. 특히 테스트 환경에서 분당 수십 건의 로그가 발생할 때, 네트워크 트래픽이 최대 1MB/s까지 증가하여 개발 네트워크에 부담을 주었습니다.

원인 분석

로그 데이터는 텍스트 기반이며 반복적인 패턴을 많이 포함하고 있어 압축률이 높은 특성이 있습니다. 하지만 기존 구현에서는 압축 없이 원본 JSON 데이터를 그대로 전송하여 네트워크 대역폭을 비효율적으로 사용하고 있었습니다.

해결 방법 (v1.0.2 적용 사항)

GZIP 압축을 사용하여 로그 데이터 전송 크기를 줄입니다. cholog.logger.compress-logs 속성이 true로 설정되어 있으면, HTTP 요청 시 Content-Encoding: gzip 헤더를 추가하고 요청 본문을 GZIP으로 압축하여 전송합니다.

// LogSenderService.java의 createRequestEntity 및 executeSend 메서드 (위 5번 항목 코드 참조)
// properties.isCompressLogs() 값에 따라 분기하여 압축 처리 및 헤더 설정

또한 ELK 스택의 Logstash 설정에 압축 해제 옵션을 추가하는 가이드를 제공할 수 있습니다.

# Logstash HTTP input 플러그인 설정 예시
input {
  http {
    port => 5000 # Logstash가 수신할 포트
    codec => json
    decompress_request => true  # 추가된 설정: 압축된 요청을 자동으로 해제
  }
}

개선 결과

네트워크 대역폭 사용량: 약 35% 감소 (평균 1MB/s → 650KB/s, 압축 활성화 시)
로그 전송 속도: 약 20% 향상
서버 간 네트워크 효율성: 약 30% 개선
로그 시스템 전체 처리량: 약 15% 증가

7. 최대 재시도 횟수를 초과한 파일 관리

문제 상황

특정 로그 배치 파일이 지속적인 오류로 인해 계속 재시도되면서 로그 처리가 지연되는 현상이 발생했습니다. 테스트 환경에서 손상된 로그 파일이 재시도 큐에 남아 매 재전송 주기(1분)마다 처리 시도와 실패를 반복하면서 다른 정상 로그의 처리까지 지연시키는 사례가 관찰되었습니다.

원인 분석

기존 구현에서는 재시도 횟수에 제한이 없어, 영구적으로 실패하는 로그 파일이 무한정 재시도 대상에 남아 시스템 리소스를 낭비하고 다른 로그 처리를 방해할 수 있었습니다.

해결 방법 (v1.0.2 적용 사항)

LogSenderService의 resendFromDisk 메서드 내에서 최대 재시도 횟수(MAX_BATCH_RETRY_ATTEMPTS, 기본값 5)를 설정하고, 이를 초과한 파일은 별도의 'retried' 폴더로 이동시켜 정상적인 로그 처리 흐름을 방해하지 않도록 구현했습니다.

// LogSenderService.java의 resendFromDisk 메서드 관련 로직
 private static final int MAX_BATCH_RETRY_ATTEMPTS = 5;
 private static final String RETRIED_FOLDER_NAME = "retried";

 if (retryCount >= MAX_BATCH_RETRY_ATTEMPTS) {
     Path retriedDir = diskQueueDir.resolve(RETRIED_FOLDER_NAME);
     // retriedDir 디렉토리 생성 (없는 경우)
     // file을 targetPath(retriedDir 내부)로 이동
     // 관련 로그 기록 및 retryCountMap에서 해당 파일 정보 제거
     continue;  // 다음 파일 처리로 진행
 }

개선 결과

로그 처리 파이프라인 안정성: 약 25% 향상
재전송 주기 당 처리 파일 수: 약 15% 증가 (문제 파일로 인한 지연 제거)
문제 파일 분리율: 100% (모든 장기 실패 파일 성공적으로 격리)
운영 모니터링 용이성: 재시도 폴더의 파일을 통해 반복적인 실패 원인 파악 가능

결론

현재 cholog-logger SDK v1.0.2 버전에는 위에서 언급된 여러 최적화 사항들이 반영되어, 로깅 시스템의 전반적인 성능과 안정성이 향상되었습니다. 특히 스레드 안전성, 메모리 효율성, 디스크 큐 관리 측면에서의 개선은 안정적인 로깅 서비스를 제공하는 데 기여하고 있습니다.

지속적인 모니터링과 피드백을 통해 앞으로도 더 많은 개선을 이어나갈 예정입니다.

Murhyun2

왜?를 생각하며 개발하기

이전 포스트

HTTP 심층 탐구: 헤더, 캐시, 쿠키와 콘텐츠 협상

다음 포스트

CHO:LOG - SSAFY 자율 프로젝트 SDK 개발

1. "Required request body is missing" 오류: 치명적인 로그 누락 해결

문제 상황

원인 분석

해결 방법

개선 결과

2. 메모리 효율성 향상: `StringBuilder` 활용 (및 `String.join`)

문제 상황

원인 분석

해결 방법

개선 결과

3. 스레드 안전성 확보: `Atomic` 클래스를 이용한 경쟁 상태 방지

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

4. 디스크 큐 안정성 향상: 실패한 로그 처리 메커니즘 개선

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

5. HTTP 헤더 처리: 압축 및 인증

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과 (압축 기능으로 인한)

6. 로그 압축 기능 구현 및 ELK 스택 연동 개선

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

7. 최대 재시도 횟수를 초과한 파일 관리

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

결론

HTTP 심층 탐구: 헤더, 캐시, 쿠키와 콘텐츠 협상

메랜샵 - 메이플랜드 프로젝트, 런칭 2주 그리고 성능 최적화

0개의 댓글

CHO:LOG - SSAFY 자율 프로젝트 SDK 개발

1. "Required request body is missing" 오류: 치명적인 로그 누락 해결

문제 상황

원인 분석

해결 방법

개선 결과

2. 메모리 효율성 향상: StringBuilder 활용 (및 String.join)

문제 상황

원인 분석

해결 방법

개선 결과

3. 스레드 안전성 확보: Atomic 클래스를 이용한 경쟁 상태 방지

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

4. 디스크 큐 안정성 향상: 실패한 로그 처리 메커니즘 개선

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

5. HTTP 헤더 처리: 압축 및 인증

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과 (압축 기능으로 인한)

6. 로그 압축 기능 구현 및 ELK 스택 연동 개선

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

7. 최대 재시도 횟수를 초과한 파일 관리

문제 상황

원인 분석

해결 방법 (v1.0.2 적용 사항)

개선 결과

결론

HTTP 심층 탐구: 헤더, 캐시, 쿠키와 콘텐츠 협상

메랜샵 - 메이플랜드 프로젝트, 런칭 2주 그리고 성능 최적화

0개의 댓글

2. 메모리 효율성 향상: `StringBuilder` 활용 (및 `String.join`)

3. 스레드 안전성 확보: `Atomic` 클래스를 이용한 경쟁 상태 방지