📗 사용자 기능 명세서

1️⃣ 로그 기록

로그 작성

• 중요도(TRACE, DEBUG, INFO, WARN, ERROR)별로 로그를 남길 수 있다.
• 로그 메시지와 함께 추가 데이터(payload)를 구조화하여 기록할 수 있다.
• 오류 발생 시 예외 정보를 함께 기록할 수 있다.
• LogBuilder 패턴으로 유연하게 로그를 구성할 수 있다.

컨텍스트 자동 포함

• 로그 발생 시간(timestamp)이 자동으로 기록된다.
• 현재 활성화된 추적 컨텍스트 정보가 자동으로 포함된다.

2️⃣ 요청 추적

분산 추적

• 요청마다 고유 추적 ID(traceId)와 스팬 ID(spanId)를 생성할 수 있다.
• W3C Trace Context 형식(traceparent)으로 변환할 수 있다.
• 외부 시스템의 traceparent 헤더를 파싱하여 컨텍스트를 이어갈 수 있다.

컨텍스트 전파

• 비동기 작업(Runnable, Callable)에 컨텍스트를 전파할 수 있다.
• 자식 스팬을 생성하여 계층적 추적이 가능하다.
• 사용자 정의 속성(userId, department, operation 등)을 추가할 수 있다.
• Baggage를 통해 서비스 간 메타데이터를 전달할 수 있다.

3️⃣ 개인정보 보호

자동 마스킹

• 주민등록번호(rrn)가 자동으로 마스킹된다.
• 신용카드번호(credit_card)가 자동으로 마스킹된다.
• 비밀번호(password)가 자동으로 마스킹된다.
• 사회보장번호(ssn)가 자동으로 마스킹된다.
• 설정을 통해 마스킹할 필드 패턴을 지정할 수 있다.

마스킹 확장

• MaskingStrategy SPI를 구현하여 커스텀 마스킹 패턴을 추가할 수 있다.

4️⃣ 로그 처리 파이프라인

인터셉터

• 로그 처리 파이프라인의 각 단계에 인터셉터를 추가할 수 있다.
• 인터셉터로 로그를 수정하거나 필터링(삭제)할 수 있다.
• 우선순위를 지정하여 인터셉터 실행 순서를 제어할 수 있다.
• 처리 단계별(PRE_PROCESS, POST_MASK, POST_ENCRYPT 등) 인터셉터를 등록할 수 있다.

5️⃣ 보안 (설정으로 활성화)

암호화

• 암호화 활성화 여부를 설정할 수 있다.
• AWS KMS 키 ID와 리전을 설정할 수 있다.
• KMS 장애 시 폴백 사용 여부를 설정할 수 있다.

무결성

• 무결성 검증 활성화 여부를 설정할 수 있다.

보안 확장

• EncryptionProvider SPI를 구현하여 커스텀 KMS를 연동할 수 있다.
• IntegrityProvider SPI를 구현하여 커스텀 무결성 검증 방식을 적용할 수 있다.

6️⃣ 전송 설정

Kafka 설정

• Kafka 부트스트랩 서버 주소를 설정할 수 있다.
• 토픽 이름을 설정할 수 있다.
• 재시도 횟수를 설정할 수 있다.
• acks, 배치 크기, 압축 방식 등을 설정할 수 있다.

폴백 설정

• 폴백 저장소 디렉토리를 설정할 수 있다.

전송 확장

• TransportProvider SPI를 구현하여 커스텀 전송 대상(Elasticsearch 등)을 추가할 수 있다.

7️⃣ 성능 설정

중복 제거

• 중복 제거 활성화 여부를 설정할 수 있다.
• 중복 감지 시간 범위(window)를 설정할 수 있다.

속도 제한

• 초당 전송량 제한을 설정할 수 있다.

서킷 브레이커

• 서킷 브레이커 실패 임계값을 설정할 수 있다.

버퍼

• 비동기 버퍼 크기를 설정할 수 있다.

8️⃣ 동작 모드

로깅 모드

• SYNC: 동기 모드 (호출 스레드에서 즉시 처리)
• ASYNC: 비동기 모드 (Virtual Thread 사용, 기본값)
• FALLBACK: 폴백 모드 (로컬 파일만 사용)

9️⃣ Spring Boot 연동

자동 설정

• secure-hr.logging.enabled로 SDK 활성화/비활성화를 설정할 수 있다.
• application.yml/properties로 모든 설정을 관리할 수 있다.

🔟 테스트 지원

LogAssert 유틸리티

• AssertJ 스타일로 로그 엔트리를 검증할 수 있다.
• 마스킹 여부를 검증할 수 있다.
• 암호화 여부를 검증할 수 있다.
• 추적 ID, 컨텍스트 정보를 검증할 수 있다.
• 무결성 해시 존재 여부를 검증할 수 있다.