# 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`