지금 진행중인 Dataracy 프로젝트에서 기존에는 @Slf4j 애노테이션을 클래스에 붙이고 직접 log.info, log.warn과 같이 에러 로그를 직접 남겼었는데 로그 시스템을 설계하고 공통 처리를 해주는 것이 더 효율적일 것 같다는 생각이 들었다.

1. 왜 운영 로그를 해야 하는가?

서비스를 운영하다 보면 단순히 “에러가 났다”를 아는 것만으로는 부족하다. 어디에서 문제가 발생했는지, 시간이 얼마나 걸렸는지, 어떤 흐름에서 실패했는지를 빠르게 파악해야 한다.

• 문제 상황 1: API 에러 로그는 남았는데 DB에서 실패했는지, Kafka 전송이 실패했는지 알 수 없다.
• 문제 상황 2: 장애가 발생했는데 로그가 제각각 찍혀 있어서 어떤 api 기능에서 발생했는지 찾기 힘들다.
• 문제 상황 3: 성능 문제가 발생했는데 어느 계층에서 지연되는지 알 수 없다.

👉 이런 문제를 해결하려면 운영 로그를 계층별로 나누고, 포맷을 통일해서 기록해야 한다.

---

2. 공통 기반: BaseLogger

모든 전용 Logger는 BaseLogger를 상속받아 구현한다.

@Slf4j
public abstract class BaseLogger {
    protected void info(String format, Object... args) {
        log.info(format, args);
    }
    protected void debug(String format, Object... args) {
        log.debug(format, args);
    }
    protected void warn(String format, Object... args) {
        log.warn(format, args);
    }
    protected void error(String format, Object... args) {
        log.error(format, args);
    }
    protected void error(Throwable t, String format, Object... args) {
        log.error(format, args, t);
    }
}

👉 효과

• 중복 제거: 모든 Logger에서 동일한 출력 방식을 사용
• 일관성: 로그 레벨·포맷을 강제
• 확장성: 새로운 Logger를 쉽게 추가 가능

---

3. LoggerFactory (싱글톤 구조)

public class LoggerFactory {
    private static final ApiLogger API_LOGGER = new ApiLogger();
    private static final ServiceLogger SERVICE_LOGGER = new ServiceLogger();
    private static final DomainLogger DOMAIN_LOGGER = new DomainLogger();
    private static final PersistenceLogger PERSISTENCE_LOGGER = new PersistenceLogger();
    private static final QueryDslLogger QUERY_DSL_LOGGER = new QueryDslLogger();
    private static final KafkaLogger KAFKA_LOGGER = new KafkaLogger();
    private static final ElasticLogger ELASTIC_LOGGER = new ElasticLogger();
    private static final RedisLogger REDIS_LOGGER = new RedisLogger();
    private static final SchedulerLogger SCHEDULER_LOGGER = new SchedulerLogger();
    private static final DistributedLockLogger DISTRIBUTED_LOCK_LOGGER = new DistributedLockLogger();
    private static final CommonLogger COMMON_LOGGER = new CommonLogger();

    public static ApiLogger api() { return API_LOGGER; }
    public static ServiceLogger service() { return SERVICE_LOGGER; }
    public static DomainLogger domain() { return DOMAIN_LOGGER; }
    public static PersistenceLogger db() { return PERSISTENCE_LOGGER; }
    public static QueryDslLogger query() { return QUERY_DSL_LOGGER; }
    public static KafkaLogger kafka() { return KAFKA_LOGGER; }
    public static ElasticLogger elastic() { return ELASTIC_LOGGER; }
    public static RedisLogger redis() { return REDIS_LOGGER; }
    public static SchedulerLogger scheduler() { return SCHEDULER_LOGGER; }
    public static DistributedLockLogger lock() { return DISTRIBUTED_LOCK_LOGGER; }
    public static CommonLogger common() { return COMMON_LOGGER; }
}

싱글톤으로 설계한 이유

• 경량 객체: Logger는 상태를 가지지 않고 단순히 로그만 찍는다. 객체를 여러 번 만들 필요가 없다.
• 일관성: 모든 계층에서 동일한 인스턴스를 사용하면 로그 포맷/정책이 보장된다.
• 편의성: LoggerFactory.db().logSave(...) 와 같은 형태로 각 계층마다 설정한 로그를 어디서든 바로 접근 가능하다.

---

4. 계층별 Logger 주요 기능

각 Logger는 계층 특성에 맞게 항목과 Duration 측정을 지원한다.

• ApiLogger: 요청/응답, 소요 시간 기록
• ServiceLogger: UseCase 단위 시작/성공, Duration
• PersistenceLogger / QueryDslLogger: DB 작업 (조회 시작/끝, CRUD), Duration
• KafkaLogger: 메시지 전송/수신/실패 기록
• RedisLogger: 캐시 조회/저장/삭제, Duration
• ElasticLogger: 색인/검색/업데이트, Duration
• DistributedLockLogger: 락 획득/실패/해제, Duration
• SchedulerLogger: 배치/스케줄 작업 시작/종료/에러 기록
• DomainLogger: 도메인 규칙 위반 기록
• CommonLogger: 범용 Start/End/Warning/Error

👉 Duration(Instant.now())을 활용해 성능 병목 지점까지 파악할 수 있다.
또한 각자의 계층에 맞는 로깅 메서드를 설정하여 구현체에서 사용한다.

---

5. 실제 코드 사용 예시

5.1 DB 작업 (UserCommandDbAdapter)

@Override
public User saveUser(User user) {
    UserEntity savedUser = userJpaRepository.save(UserEntityMapper.toEntity(user));
    LoggerFactory.db().logSave("UserEntity", String.valueOf(savedUser.getId()), "DB에 유저를 저장하였습니다.");
    return UserEntityMapper.toDomain(savedUser);
}

@Override
public void changePassword(Long userId, String encodePassword) {
    UserEntity userEntity = userJpaRepository.findById(userId)
            .orElseThrow(() -> {
                LoggerFactory.db().logWarning("UserEntity", "[비밀번호 변경] 사용자를 찾을 수 없습니다. userId=" + userId);
                return new UserException(UserErrorStatus.NOT_FOUND_USER);
            });
    userEntity.changePassword(encodePassword);
    LoggerFactory.db().logUpdate("UserEntity", String.valueOf(userEntity.getId()), "새 비밀번호를 변경하였습니다.");
}

👉 효과:

• 어떤 엔티티(UserEntity)에 어떤 작업(저장/수정)이 일어났는지 명확하게 기록
• 예외 상황까지 로깅(logWarning)

---

5.2 Kafka 이벤트 발송 (LikeKafkaProducerAdapter)

kafkaTemplate.send(TOPIC_PROJECT_LIKE_INCREASE, String.valueOf(targetId), targetId)
    .whenComplete((result, ex) -> {
        if (ex == null) {
            LoggerFactory.kafka().logProduce(TOPIC_PROJECT_LIKE_INCREASE,
                "프로젝트 좋아요 이벤트 발송됨: projectId=" + targetId);
        } else {
            LoggerFactory.kafka().logError(TOPIC_PROJECT_LIKE_INCREASE,
                "프로젝트 좋아요 이벤트 발송 처리 실패: projectId=" + targetId, ex);
        }
    });

👉 효과:

• 이벤트 발송 성공/실패를 즉시 로그로 구분 가능
• 장애 시 토픽명 + 대상 ID + 예외 정보가 그대로 남아 원인 분석이 빠르다

  이렇게 각자의 계층마다의 커스텀 운영 로그를 사용한다.

---

6. 그래서, 운영 로그의 핵심은?

6.1 왜 필요한가

• 장애 시 “어디서” 문제가 났는지 계층별로 바로 알 수 있다.
• 성능 분석 시 Duration으로 병목 구간을 빠르게 찾을 수 있다.
• 로그를 보는 사람(개발/운영/분석자)마다 필요한 정보를 구분할 수 있다.

6.2 어떻게 구현했는가

• BaseLogger → 공통 기반
• LoggerFactory → 싱글톤 전역 접근
• 각 계층별 Logger → 포맷 통일 + Duration 측정 등

6.3 어떤 효과가 있는가

• 가독성: [DB 저장] ..., [Kafka 전송] ... → 한 줄만 봐도 출처 식별
• 분석 효율성: 장애/성능 문제 발생 시 원하는 로그만 빠르게 필터링
• 표준화: 팀 전체가 동일한 패턴으로 로그 작성 → 협업 효율 증가

---

7. 마무리

행동 로그(MDC 기반)는 사용자의 “무엇을 했는가(어떤 기능)”를 추적한다면,
운영 로그는 시스템의 “어떻게 동작했는가”를 추적한다.

운영 로그를 계층별 Logger + 싱글톤 Factory 구조로 구현함으로써,

• 장애 대응 속도가 빨라지고
• 성능 병목 지점이 드러나고
• 편의성있게 필터링 할 수 있으며
• 로그 문화가 표준화되었다고 생각한다.

즉, 운영 로그는 단순한 로그 출력이 아니라, 서비스 안정성과 운영 효율성을 뒷받침하는 핵심 인프라다.