# 로깅 규칙 참조

**작성일**: 2025-12-06
**목적**: 로그 일관성 유지, 디버깅 효율성 향상

---

## 로그 레벨 사용 규칙

| 레벨 | 사용 시점 | 예시 |
|------|-----------|------|
| `DEBUG` | 상세 디버깅 정보 | 변수 값, 함수 진입/종료 |
| `INFO` | 정상 동작 정보 | 요청 처리, 상태 변경 |
| `WARNING` | 예상 가능한 문제 | 재시도, 폴백 처리 |
| `ERROR` | 처리 실패 | 예외 발생, API 오류 |
| `CRITICAL` | 시스템 중단 | DB 연결 실패, 서비스 다운 |

**참고**: `rb8001/app/core/logger.py`

---

## 로그 포맷

### 구조화된 로그
```python
logger.info(f"User {user_id} authenticated", extra={
    "user_id": user_id,
    "action": "authenticate"
})
```

### JSON 로깅
- 형식: JSON (python-json-logger 사용)
- 필드: `time`, `level`, `module`, `msg`

**참고**: `rb8001/app/core/logger.py`

---

## 로그 위치

### 컨테이너 내부
- 경로: `/code/logs/[서비스명].log`
- 예시: `/code/logs/rb8001.log`

### 호스트 (백업)
- 경로: `/mnt/51123logs/[서비스명]/`
- 백업 시간: 매일 03:00

**참고**: `AGENTS.md:133-137`

---

## 로그 확인 방법

### 실시간 로그
```bash
docker logs [컨테이너명] --tail 100
```

### 파일 로그
```bash
tail -f /code/logs/[서비스명].log
```

### 에러 필터링
```bash
docker logs [컨테이너명] | grep -iE "error|warn|fail"
```

**참고**: `AGENTS.md:133-137`

---

## 로그 보관

### Docker JSON 로그
- 위치: `/var/lib/docker/containers/*/json.log`
- 권한: sudo 필요

### OpenSearch
- 주소: http://192.168.219.45:9200
- 인덱스: `dataprepper-static` (서비스 로그)
- 일별 인덱스: `dataprepper-YYYY.MM.DD` (fluent-bit 로그)

**참고**: `AGENTS.md:137-142`

---

## 로깅 모범 사례

### DO
- 요청/응답 로깅 (INFO)
- 에러 상세 정보 포함 (ERROR)
- 사용자 ID 포함 (개인정보 제외)

### DON'T
- 민감 정보 로깅 (비밀번호, 토큰)
- 과도한 DEBUG 로그 (프로덕션)
- 중복 로그 (같은 정보 반복)

---

**업데이트**: 로깅 규칙 변경 시 즉시 반영