로깅

작성자

익명

작성일

2026.07.19

조회수

버전

로깅 (Logging)

1. 개요

로깅(Logging)이란 소프트웨어 실행 과정에서 발생하는 주요 이벤트, 상태 변화, 오류 등의 정보를 기록으로 남기는 행위 또는 그 시스템을 의미한다.

로깅의 주된 목적은 시스템의 가시성(Visibility)을 확보하여, 장애 발생 시 원인을 빠르게 분석(Troubleshooting)하고 시스템의 성능 및 사용자 행동 패턴을 모니터링하는 데 있다. 많은 입문자가 사용하는 단순 출력 함수(print, console.log 등)는 표준 출력(stdout)에 내용을 표시할 뿐, 기록의 보존, 레벨별 필터링, 출력 대상 제어 기능이 없어 실제 운영 환경에서는 사용할 수 없다. 반면, 전문적인 로깅 프레임워크는 로그의 중요도에 따라 기록 여부를 결정하고, 파일, 데이터베이스, 외부 서버 등 다양한 저장소로 로그를 전송하는 기능을 제공한다.

2. 로깅의 작동 원리 및 구성 요소

로깅 시스템은 일반적으로 메시지 생성부터 최종 저장까지 단계별 역할을 분담하는 파이프라인 구조를 가진다.

Logger (로거): 애플리케이션 코드에서 로그 기록을 요청하는 진입점이다. 로그 레벨을 설정하여 특정 수준 이상의 메시지만 통과시키도록 제어한다.
Handler/Appender (핸들러/어펜더): 생성된 로그 메시지를 어디로 보낼지 결정하는 출력 대상 제어기이다. 콘솔, 파일, 네트워크 소켓, 이메일 등 다양한 출력처를 설정할 수 있다.
Formatter (포맷터): 로그 메시지의 출력 형식을 정의한다. 타임스탬프, 로그 레벨, 스레드 ID, 클래스명 등을 포함하여 일관된 형태로 변환한다.

[표 1] 로깅 구성 요소의 역할 비교

구성 요소	역할	책임	비고
Logger	메시지 생성 및 필터링	어떤 로그를 남길 것인가?	레벨 설정 (Level Filtering)
Handler (Appender)	출력 대상 지정	로그를 어디에 저장할 것인가?	File, Console, Remote Server
Formatter	메시지 구조화	로그를 어떤 형태로 보여줄 것인가?	JSON, Plain Text, CSV

3. 로그 레벨 (Log Levels)

로그 레벨은 메시지의 중요도와 긴급도를 구분하는 척도이다. 이를 통해 운영 환경에서는 불필요한 상세 로그를 배제하고 치명적인 오류만 기록함으로써 저장 공간을 효율적으로 관리하고 분석 노이즈를 줄일 수 있다.

[표 2] 로그 레벨 정의 및 사용 사례

레벨	정의	사용 사례	출력 여부 (운영 환경)
TRACE	가장 상세한 정보	메서드 진입/종료, 변수 값 추적	일반적으로 제외
DEBUG	개발 단계의 진단 정보	쿼리 실행 결과, API 요청/응답 값	개발/스테이징 환경만
INFO	정상적인 상태 변경 정보	서버 시작/종료, 사용자 로그인, 배치 완료	기본 기록 대상
WARN	잠재적 위험 상황	API 응답 지연, deprecated API 호출	기록 및 모니터링
ERROR	요청 처리 실패 (복구 가능)	DB 연결 일시 실패, 잘못된 입력 값 처리	즉시 확인 필요
FATAL	시스템 중단 (복구 불가능)	메모리 부족(OOM), 핵심 설정 파일 누락	즉시 알림(Alert) 발생
주: 로그 레벨은 계층적 구조를 가지며, 설정된 로그 레벨(예: INFO) 이상의 모든 상위 레벨 로그가 출력된다.

4. 로깅 전략 및 모범 사례

효율적인 로깅을 위해서는 단순히 기록하는 것을 넘어, 분석 가능한 형태로 설계하는 전략이 필요하다.

구조화된 로깅 (Structured Logging): 단순 텍스트가 아닌 JSON과 같은 정형 데이터 형식으로 로그를 남기는 방식이다. 이는 로그 수집 도구(Elasticsearch 등)에서 특정 필드를 기준으로 빠르게 검색하고 집계하는 것을 가능하게 한다.

JSON 예시 포맷:

        {
          "timestamp": "2023-10-27T10:15:30.123Z",
          "level": "ERROR",
          "service": "order-service",
          "trace_id": "a1b2c3d4e5f6",
          "user_id": "user_123",
          "message": "Payment failed",
          "exception": "PaymentGatewayTimeoutException",
          "context": { "order_id": "ORD-999", "amount": 50000 }
        }

상관관계 ID (Correlation ID/Trace ID): 분산 시스템(마이크로서비스 아키텍처)에서는 하나의 요청이 여러 서버를 거치므로, 요청 진입 시 고유 ID를 부여하고 모든 로그에 이를 포함시킨다. 이를 통해 서로 다른 서버에 흩어진 로그들을 하나의 요청 흐름으로 묶어 추적할 수 있다.
로그 회전 (Log Rotation) 및 보존 정책 (Retention Policy):
- 로그 회전: 로그 파일이 무한정 커지는 것을 방지하기 위해 특정 기준에 따라 파일을 교체한다.
  - 크기 기반: 파일이 10MB, 100MB 등 설정된 크기에 도달하면 새 파일 생성.
  - 기간 기반: 매일(Daily), 매시간(Hourly) 단위로 파일을 분리하여 생성.
- 보존 정책: 법적 근거(개인정보보호법 등)나 스토리지 비용 관리를 위해 로그를 언제 삭제하거나 콜드 스토리지(S3 Glacier 등)로 옮길 것인지에 대한 정책을 수립해야 한다.
민감 정보 마스킹 (Masking): 개인정보 보호법 및 보안 규정에 따라 비밀번호, 주민등록번호, 신용카드 번호 등 민감한 데이터는 ****와 같이 마스킹 처리하여 기록해야 한다.

5. 로그 분석 및 모니터링

기록된 로그는 사후 분석뿐만 아니라 실시간 모니터링을 통해 시스템의 건강 상태를 확인하는 데 사용된다.

로그 집계 (Aggregation): 여러 대의 서버에서 발생하는 로그를 한곳으로 모으는 과정이다.
로그 분석 (Analysis): 수집된 로그에서 특정 패턴(예: 5분간 500 에러 100건 발생)을 찾아내어 장애 징후를 포착한다.
알림 (Alerting): FATAL 또는 ERROR 레벨의 로그가 임계치를 초과할 경우 슬랙(Slack), 이메일, PagerDuty 등을 통해 담당자에게 즉시 알림을 전송한다.

6. 로깅 도구 및 생태계

현대적인 소프트웨어 개발에서는 언어별 표준 라이브러리와 중앙 집중형 관리 시스템을 조합하여 사용한다.

언어별 대표 라이브러리 및 예시

Java: SLF4J (추상화 계층), Log4j2, Logback

    logger.info("Order processed successfully. OrderID: {}", orderId);

Python: logging (표준 라이브러리), Loguru

    logger.info(f"User {user_id} logged in")

JavaScript/Node.js: Winston, Bunyan, Pino

    logger.error("Database connection failed", { error: err, retry_count: 3 });

중앙 집중형 로그 관리 시스템

ELK Stack: Elasticsearch(검색/분석), Logstash(수집/가공), Kibana(시각화)의 조합으로 가장 널리 쓰인다.
Splunk: 강력한 분석 기능을 제공하는 상용 로그 관리 플랫폼이다.
Grafana Loki: Prometheus와 유사한 방식으로 로그를 수집하며, 리소스 사용량이 적은 것이 특징이다.

[표 3] 로그 저장소별 장단점 비교

저장소 유형	장점	단점	적합한 용도
로컬 파일	설정이 매우 간단, 쓰기 속도가 빠름	서버 분산 시 수집 어려움, 디스크 관리 필요	소규모 프로젝트, 단일 서버
RDBMS	쿼리를 통한 정밀한 분석 가능	쓰기 부하가 큼, 데이터량 증가 시 성능 저하	감사 로그(Audit Log), 중요 이벤트
NoSQL/Search Engine	대량 데이터 검색 및 집계 속도가 매우 빠름	인덱싱 비용 발생, 인프라 구축 복잡도 높음	대규모 서비스, 실시간 모니터링
Cloud Watch/Stackdriver	인프라 관리 불필요, 클라우드 서비스 연동	비용 발생, 벤더 종속성(Lock-in)	클라우드 네이티브 환경

7. 안티 패턴 및 주의사항

잘못된 로깅 습관은 시스템 성능을 저하시키거나 보안 사고의 원인이 될 수 있다.

과도한 로깅 (Over-logging): 모든 변수 값을 INFO 레벨로 남기는 행위는 디스크 I/O 부하를 일으키고 정작 중요한 로그를 찾기 어렵게 만든다.
로그 내 민감 정보 노출: 사용자 비밀번호, API 키, 세션 토큰 등을 로그에 그대로 남기는 것은 심각한 보안 취약점이다.
동기식 로깅 (Synchronous Logging): 로그를 기록하는 동안 애플리케이션의 메인 스레드가 대기하는 방식이다. 트래픽이 많은 시스템에서는 비동기(Asynchronous) 로깅을 사용하여 성능 저하를 막아야 한다.
의미 없는 메시지: "Error occurred", "Process started"와 같이 맥락이 없는 메시지는 분석 시 도움이 되지 않는다. 어떤 입력값에서 어떤 오류가 발생했는지 구체적인 컨텍스트를 포함해야 한다.

8. 구현 예제 (Python)

다음은 Python의 표준 logging 라이브러리를 사용하여 파일 저장과 콘솔 출력을 동시에 수행하고, 로그 회전을 적용한 표준적인 구현 방식이다.

import logging
from logging.handlers import RotatingFileHandler

# 1. 로거 생성
logger = logging.getLogger("MyAppLogger")
# [주의] 로거의 레벨이 핸들러의 레벨보다 높으면 핸들러까지 로그가 전달되지 않음
logger.setLevel(logging.DEBUG) # 전체 로그 레벨 설정

# 2. 포맷터 정의 (시간 - 이름 - 레벨 - 메시지)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# 3. 핸들러 설정
# 콘솔 핸들러: INFO 레벨 이상만 출력
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_handler.setFormatter(formatter)

# 파일 핸들러: DEBUG 레벨 이상 기록, 최대 5MB 파일 3개까지 유지 (Log Rotation)
# maxBytes: 파일 크기 기준 회전, backupCount: 보관할 이전 파일 개수
file_handler = RotatingFileHandler('app.log', maxBytes=5*1024*1024, backupCount=3)
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(formatter)

# 4. 로거에 핸들러 추가
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# 5. 실제 사용 예시
def divide(a, b):
    logger.debug(f"입력값: a={a}, b={b}") # 개발용 상세 로그
    try:
        result = a / b
        logger.info("나눗셈 계산 성공") # 정상 흐름 로그
        return result
    except ZeroDivisionError:
        logger.error("0으로 나눌 수 없습니다.") # 에러 로그
        return None

divide(10, 2)
divide(10, 0)

📝 마크다운 원본

이 문서의 마크다운 원본 내용입니다.

# 로깅 (Logging)

## 1. 개요
로깅(Logging)이란 소프트웨어 실행 과정에서 발생하는 주요 이벤트, 상태 변화, 오류 등의 정보를 기록으로 남기는 행위 또는 그 시스템을 의미한다.

로깅의 주된 목적은 시스템의 가시성(Visibility)을 확보하여, 장애 발생 시 원인을 빠르게 분석(Troubleshooting)하고 시스템의 성능 및 사용자 행동 패턴을 모니터링하는 데 있다. 많은 입문자가 사용하는 단순 출력 함수(`print`, `console.log` 등)는 표준 출력(stdout)에 내용을 표시할 뿐, 기록의 보존, 레벨별 필터링, 출력 대상 제어 기능이 없어 실제 운영 환경에서는 사용할 수 없다. 반면, 전문적인 로깅 프레임워크는 로그의 중요도에 따라 기록 여부를 결정하고, 파일, 데이터베이스, 외부 서버 등 다양한 저장소로 로그를 전송하는 기능을 제공한다.

## 2. 로깅의 작동 원리 및 구성 요소
로깅 시스템은 일반적으로 메시지 생성부터 최종 저장까지 단계별 역할을 분담하는 파이프라인 구조를 가진다.

1. **Logger (로거)**: 애플리케이션 코드에서 로그 기록을 요청하는 진입점이다. 로그 레벨을 설정하여 특정 수준 이상의 메시지만 통과시키도록 제어한다.
2. **Handler/Appender (핸들러/어펜더)**: 생성된 로그 메시지를 어디로 보낼지 결정하는 출력 대상 제어기이다. 콘솔, 파일, 네트워크 소켓, 이메일 등 다양한 출력처를 설정할 수 있다.
3. **Formatter (포맷터)**: 로그 메시지의 출력 형식을 정의한다. 타임스탬프, 로그 레벨, 스레드 ID, 클래스명 등을 포함하여 일관된 형태로 변환한다.

### [표 1] 로깅 구성 요소의 역할 비교
| 구성 요소 | 역할 | 책임 | 비고 |
| :--- | :--- | :--- | :--- |
| **Logger** | 메시지 생성 및 필터링 | 어떤 로그를 남길 것인가? | 레벨 설정 (Level Filtering) |
| **Handler (Appender)** | 출력 대상 지정 | 로그를 어디에 저장할 것인가? | File, Console, Remote Server |
| **Formatter** | 메시지 구조화 | 로그를 어떤 형태로 보여줄 것인가? | JSON, Plain Text, CSV |

## 3. 로그 레벨 (Log Levels)
로그 레벨은 메시지의 중요도와 긴급도를 구분하는 척도이다. 이를 통해 운영 환경에서는 불필요한 상세 로그를 배제하고 치명적인 오류만 기록함으로써 저장 공간을 효율적으로 관리하고 분석 노이즈를 줄일 수 있다.

### [표 2] 로그 레벨 정의 및 사용 사례
| 레벨 | 정의 | 사용 사례 | 출력 여부 (운영 환경) |
| :--- | :--- | :--- | :--- |
| **TRACE** | 가장 상세한 정보 | 메서드 진입/종료, 변수 값 추적 | 일반적으로 제외 |
| **DEBUG** | 개발 단계의 진단 정보 | 쿼리 실행 결과, API 요청/응답 값 | 개발/스테이징 환경만 |
| **INFO** | 정상적인 상태 변경 정보 | 서버 시작/종료, 사용자 로그인, 배치 완료 | 기본 기록 대상 |
| **WARN** | 잠재적 위험 상황 | API 응답 지연, deprecated API 호출 | 기록 및 모니터링 |
| **ERROR** | 요청 처리 실패 (복구 가능) | DB 연결 일시 실패, 잘못된 입력 값 처리 | 즉시 확인 필요 |
| **FATAL** | 시스템 중단 (복구 불가능) | 메모리 부족(OOM), 핵심 설정 파일 누락 | 즉시 알림(Alert) 발생 |
*주: 로그 레벨은 계층적 구조를 가지며, 설정된 로그 레벨(예: INFO) 이상의 모든 상위 레벨 로그가 출력된다.*

## 4. 로깅 전략 및 모범 사례
효율적인 로깅을 위해서는 단순히 기록하는 것을 넘어, 분석 가능한 형태로 설계하는 전략이 필요하다.

*   **구조화된 로깅 (Structured Logging)**: 단순 텍스트가 아닌 JSON과 같은 정형 데이터 형식으로 로그를 남기는 방식이다. 이는 로그 수집 도구(Elasticsearch 등)에서 특정 필드를 기준으로 빠르게 검색하고 집계하는 것을 가능하게 한다.
    *   **JSON 예시 포맷**:
        ```json
        {
          "timestamp": "2023-10-27T10:15:30.123Z",
          "level": "ERROR",
          "service": "order-service",
          "trace_id": "a1b2c3d4e5f6",
          "user_id": "user_123",
          "message": "Payment failed",
          "exception": "PaymentGatewayTimeoutException",
          "context": { "order_id": "ORD-999", "amount": 50000 }
        }
        ```
*   **상관관계 ID (Correlation ID/Trace ID)**: 분산 시스템(마이크로서비스 아키텍처)에서는 하나의 요청이 여러 서버를 거치므로, 요청 진입 시 고유 ID를 부여하고 모든 로그에 이를 포함시킨다. 이를 통해 서로 다른 서버에 흩어진 로그들을 하나의 요청 흐름으로 묶어 추적할 수 있다.
*   **로그 회전 (Log Rotation) 및 보존 정책 (Retention Policy)**: 
    *   **로그 회전**: 로그 파일이 무한정 커지는 것을 방지하기 위해 특정 기준에 따라 파일을 교체한다.
        *   **크기 기반**: 파일이 10MB, 100MB 등 설정된 크기에 도달하면 새 파일 생성.
        *   **기간 기반**: 매일(Daily), 매시간(Hourly) 단위로 파일을 분리하여 생성.
    *   **보존 정책**: 법적 근거(개인정보보호법 등)나 스토리지 비용 관리를 위해 로그를 언제 삭제하거나 콜드 스토리지(S3 Glacier 등)로 옮길 것인지에 대한 정책을 수립해야 한다.
*   **민감 정보 마스킹 (Masking)**: 개인정보 보호법 및 보안 규정에 따라 비밀번호, 주민등록번호, 신용카드 번호 등 민감한 데이터는 `****`와 같이 마스킹 처리하여 기록해야 한다.

## 5. 로그 분석 및 모니터링
기록된 로그는 사후 분석뿐만 아니라 실시간 모니터링을 통해 시스템의 건강 상태를 확인하는 데 사용된다.

*   **로그 집계 (Aggregation)**: 여러 대의 서버에서 발생하는 로그를 한곳으로 모으는 과정이다.
*   **로그 분석 (Analysis)**: 수집된 로그에서 특정 패턴(예: 5분간 500 에러 100건 발생)을 찾아내어 장애 징후를 포착한다.
*   **알림 (Alerting)**: `FATAL` 또는 `ERROR` 레벨의 로그가 임계치를 초과할 경우 슬랙(Slack), 이메일, PagerDuty 등을 통해 담당자에게 즉시 알림을 전송한다.

## 6. 로깅 도구 및 생태계
현대적인 소프트웨어 개발에서는 언어별 표준 라이브러리와 중앙 집중형 관리 시스템을 조합하여 사용한다.

### 언어별 대표 라이브러리 및 예시
*   **Java**: SLF4J (추상화 계층), Log4j2, Logback
    ```java
    logger.info("Order processed successfully. OrderID: {}", orderId);
    ```
*   **Python**: `logging` (표준 라이브러리), Loguru
    ```python
    logger.info(f"User {user_id} logged in")
    ```
*   **JavaScript/Node.js**: Winston, Bunyan, Pino
    ```javascript
    logger.error("Database connection failed", { error: err, retry_count: 3 });
    ```

### 중앙 집중형 로그 관리 시스템
*   **ELK Stack**: Elasticsearch(검색/분석), Logstash(수집/가공), Kibana(시각화)의 조합으로 가장 널리 쓰인다.
*   **Splunk**: 강력한 분석 기능을 제공하는 상용 로그 관리 플랫폼이다.
*   **Grafana Loki**: Prometheus와 유사한 방식으로 로그를 수집하며, 리소스 사용량이 적은 것이 특징이다.

### [표 3] 로그 저장소별 장단점 비교
| 저장소 유형 | 장점 | 단점 | 적합한 용도 |
| :--- | :--- | :--- | :--- |
| **로컬 파일** | 설정이 매우 간단, 쓰기 속도가 빠름 | 서버 분산 시 수집 어려움, 디스크 관리 필요 | 소규모 프로젝트, 단일 서버 |
| **RDBMS** | 쿼리를 통한 정밀한 분석 가능 | 쓰기 부하가 큼, 데이터량 증가 시 성능 저하 | 감사 로그(Audit Log), 중요 이벤트 |
| **NoSQL/Search Engine** | 대량 데이터 검색 및 집계 속도가 매우 빠름 | 인덱싱 비용 발생, 인프라 구축 복잡도 높음 | 대규모 서비스, 실시간 모니터링 |
| **Cloud Watch/Stackdriver** | 인프라 관리 불필요, 클라우드 서비스 연동 | 비용 발생, 벤더 종속성(Lock-in) | 클라우드 네이티브 환경 |

## 7. 안티 패턴 및 주의사항
잘못된 로깅 습관은 시스템 성능을 저하시키거나 보안 사고의 원인이 될 수 있다.

*   **과도한 로깅 (Over-logging)**: 모든 변수 값을 `INFO` 레벨로 남기는 행위는 디스크 I/O 부하를 일으키고 정작 중요한 로그를 찾기 어렵게 만든다.
*   **로그 내 민감 정보 노출**: 사용자 비밀번호, API 키, 세션 토큰 등을 로그에 그대로 남기는 것은 심각한 보안 취약점이다.
*   **동기식 로깅 (Synchronous Logging)**: 로그를 기록하는 동안 애플리케이션의 메인 스레드가 대기하는 방식이다. 트래픽이 많은 시스템에서는 비동기(Asynchronous) 로깅을 사용하여 성능 저하를 막아야 한다.
*   **의미 없는 메시지**: `"Error occurred"`, `"Process started"`와 같이 맥락이 없는 메시지는 분석 시 도움이 되지 않는다. 어떤 입력값에서 어떤 오류가 발생했는지 구체적인 컨텍스트를 포함해야 한다.

## 8. 구현 예제 (Python)
다음은 Python의 표준 `logging` 라이브러리를 사용하여 파일 저장과 콘솔 출력을 동시에 수행하고, 로그 회전을 적용한 표준적인 구현 방식이다.

```python
import logging
from logging.handlers import RotatingFileHandler

# 1. 로거 생성
logger = logging.getLogger("MyAppLogger")
# [주의] 로거의 레벨이 핸들러의 레벨보다 높으면 핸들러까지 로그가 전달되지 않음
logger.setLevel(logging.DEBUG) # 전체 로그 레벨 설정

# 2. 포맷터 정의 (시간 - 이름 - 레벨 - 메시지)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# 3. 핸들러 설정
# 콘솔 핸들러: INFO 레벨 이상만 출력
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_handler.setFormatter(formatter)

# 파일 핸들러: DEBUG 레벨 이상 기록, 최대 5MB 파일 3개까지 유지 (Log Rotation)
# maxBytes: 파일 크기 기준 회전, backupCount: 보관할 이전 파일 개수
file_handler = RotatingFileHandler('app.log', maxBytes=5*1024*1024, backupCount=3)
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(formatter)

# 4. 로거에 핸들러 추가
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# 5. 실제 사용 예시
def divide(a, b):
    logger.debug(f"입력값: a={a}, b={b}") # 개발용 상세 로그
    try:
        result = a / b
        logger.info("나눗셈 계산 성공") # 정상 흐름 로그
        return result
    except ZeroDivisionError:
        logger.error("0으로 나눌 수 없습니다.") # 에러 로그
        return None

divide(10, 2)
divide(10, 0)
```

AI 생성 콘텐츠 안내

이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.

주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.

위키너와나

로깅