forked from baron/baron-sso
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# Backend Log Policy
|
|
|
|
## 1. 목적
|
|
- Backend 서버 로그의 기본 레벨과 운영 중 일시적 디버그 확장 규칙을 정의합니다.
|
|
- 운영 환경에서 과도한 로그 노출을 피하면서, 장애 분석이 필요한 경우에는 명시적으로 진단 로그를 확장할 수 있게 합니다.
|
|
|
|
## 2. 기준 변수
|
|
- `APP_ENV`
|
|
- `BACKEND_LOG_LEVEL` (선택 override)
|
|
|
|
## 3. 기본 동작
|
|
|
|
### 3.1 기본 레벨 결정
|
|
- `APP_ENV=dev|local|development`
|
|
- 기본 로그 레벨: `debug`
|
|
- 기본 출력 형식: text
|
|
- 그 외 환경(`stage`, `production`, `prod` 등)
|
|
- 기본 로그 레벨: `info`
|
|
- 기본 출력 형식: JSON
|
|
|
|
### 3.2 명시 override
|
|
- `BACKEND_LOG_LEVEL`이 설정되면 `APP_ENV` 기본값보다 우선합니다.
|
|
- 허용 값:
|
|
- `debug`
|
|
- `info`
|
|
- `warn`
|
|
- `error`
|
|
|
|
예시:
|
|
```env
|
|
APP_ENV=stage
|
|
BACKEND_LOG_LEVEL=debug
|
|
```
|
|
|
|
위 설정이면 stage 환경이더라도 backend `slog`는 `debug`로 동작합니다.
|
|
|
|
## 4. 운영 가이드
|
|
- 운영/스테이징에서 장애 분석이 필요할 때만 `BACKEND_LOG_LEVEL=debug`를 일시적으로 설정합니다.
|
|
- 이슈 분석이 끝나면 즉시 기본값으로 되돌리는 것을 권장합니다.
|
|
- 기본 레벨(`info`)에서는 핵심 상태 변화와 경고/오류를 중심으로 남기고, 디버그 전용 진단 필드는 숨깁니다.
|
|
|
|
## 5. Headless Login 진단 로그
|
|
- `POST /api/v1/auth/headless/password/login` 같은 headless 로그인 경로는 기본적으로 `reason_code` 중심의 구조화 로그를 남깁니다.
|
|
- `BACKEND_LOG_LEVEL=debug` 또는 `APP_ENV=dev|local|development`일 때만 아래 진단 필드를 추가로 남깁니다.
|
|
- `expected_audiences`
|
|
- `received_audiences`
|
|
- `received_kid`
|
|
- `claim_issuer`
|
|
- `claim_subject`
|
|
- `claim_expires_at`
|
|
- `claim_not_before`
|
|
- `claim_issued_at`
|
|
- 민감 정보는 계속 로그에 남기지 않습니다.
|
|
- raw `client_assertion`
|
|
- password
|
|
- session token / cookie
|
|
|
|
## 6. 구현 위치
|
|
- logger 초기화: `backend/cmd/server/main.go`
|
|
- 레벨 결정 로직: `backend/internal/logger/logger.go`
|
|
- headless 로그인 debug 진단 필드: `backend/internal/handler/auth_handler.go`
|
|
|
|
## 7. 검증
|
|
```bash
|
|
cd backend
|
|
go test ./internal/logger -v
|
|
go test ./cmd/server -run 'TestNewErrorHandler_' -v
|
|
go test ./internal/handler -run 'TestHeadlessPasswordLogin_(DebugLogIncludesDiagnostics|InfoLogOmitsDebugDiagnostics)$' -v
|
|
```
|
|
|
|
## 8. 관련 문서
|
|
- `README.md`
|
|
- `docs/client-log-policy.md`
|
|
- wiki update draft: `docs/wiki-error-handling-policy-backend-log-update.md`
|