baron-sso/docs/backend-log-policy.md

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

예시:

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. 검증

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