백엔드 에러 처리 개선: 사용자 친화적 화면, 자동 복구, 정보 수집 시스템 구축 사례

백엔드 에러 처리 개선: 사용자 친화적 화면, 자동 복구, 정보 수집 시스템 구축 사례

기존의 'Application error' 메시지가 사용자에게 혼란을 주고, 에러 발생 시 자동 복구 및 정보 수집 기능이 없어 운영에 어려움을 겪고 있었습니다. 이 글에서는 이러한 문제를 해결하고 운영 안정성을 높인 경험을 공유하고자 합니다.

시도와 함정

먼저, 'Application error'라는 딱딱한 메시지를 사용자 친화적인 화면으로 바꾸는 작업을 시작했습니다. 사용자에게 어떤 문제가 발생했는지, 그리고 어떻게 대처해야 하는지 명확하게 안내하는 것이 목표였습니다.

<!-- 기존 에러 페이지 (예시) -->
<h1>Application Error</h1>
<p>An unexpected error occurred. Please try again later.</p>

이어서 에러 발생 시 자동으로 시스템을 복구하는 기능을 추가했습니다. 반복되는 에러로 인한 서비스 중단을 최소화하기 위해서였죠. 또한, 에러가 발생했을 때 관련 정보를 자동으로 수집하는 시스템을 구축했습니다. 어떤 종류의 에러가 자주 발생하는지 파악하고 근본적인 해결책을 찾는 데 도움이 될 것이라 생각했습니다.

# 에러 발생 시 자동 복구 로직 (개념적 예시)
def handle_error_and_recover(error_details):
    log_error(error_details)
    if is_recoverable(error_details):
        attempt_recovery()
        return "Recovered successfully"
    else:
        trigger_alert_to_ops()
        return "Error logged, manual intervention required"
def is_recoverable(error_details):
# 특정 에러 코드나 패턴에 따라 복구 가능 여부 판단
return error_details.get("code") in ["TEMP_UNAVAILABLE", "NETWORK_ISSUE"]
def attempt_recovery():
# 서비스 재시작, 캐시 초기화 등 복구 시도
print("Attempting to restart service...")
# 실제 복구 로직 구현
pass

처음에는 에러 메시지를 단순히 보기 좋게 바꾸는 것부터 시작했습니다. 하지만 사용자 친화적인 화면을 만드는 것만으로는 근본적인 문제를 해결할 수 없었습니다. 에러 발생 시 시스템이 멈추는 현상이나, 에러 발생 원인을 파악하기 어려운 점들이 여전히 남아있었죠. 특히 자동 복구 기능을 구현하는 과정에서 예상치 못한 예외 상황들이 발생하여 몇 시간을 삽질하기도 했습니다.

// 에러 정보 수집 시 로그 예시
{
  "timestamp": "2026-06-11T10:30:00Z",
  "error_code": "DB_CONNECTION_FAILED",
  "message": "Failed to connect to database: timeout expired",
  "service_name": "user-service",
  "request_id": "abc123xyz789",
  "stack_trace": "...",
  "environment": "production"
}

원인

기존의 'Application error' 메시지는 기술적인 내용을 그대로 노출하여 사용자에게 불필요한 혼란을 야기했습니다. 또한, 에러 발생 시 시스템이 스스로 복구할 수 있는 메커니즘이 없었고, 에러 발생 시점에 대한 정보 수집이 체계적으로 이루어지지 않아 문제 해결에 많은 시간이 소요되었습니다.

해결

사용자 친화적인 에러 화면을 구현하여 기술적인 용어 대신 사용자가 이해하기 쉬운 메시지와 함께 다음 단계를 안내하도록 변경했습니다.

<!-- 개선된 에러 페이지 (예시) -->
<h1>죄송합니다, 일시적인 문제가 발생했습니다.</h1>
<p>현재 서비스 이용에 불편을 드려 죄송합니다. 잠시 후 다시 시도해 주시면 정상적으로 이용하실 수 있습니다.</p>
<p>문제가 지속될 경우, 고객센터로 문의해 주시기 바랍니다.</p>

에러 발생 시 자동으로 시스템을 재시작하거나 관련 설정을 조정하는 등의 복구 로직을 추가했습니다.

# 개선된 에러 처리 및 복구 로직 (개념적 예시)
def robust_error_handler(exception):
    error_info = collect_error_details(exception)
    log_error_to_central_system(error_info)
if is_service_degraded(error_info):
    attempt_auto_recovery(error_info)
else:
    notify_operations_team(error_info)

display_user_friendly_error_page()

def collect_error_details(exception):
# 예외 객체에서 필요한 정보 추출 (에러 코드, 메시지, 스택 트레이스 등)
return {
"code": getattr(exception, "error_code", "UNKNOWN"),
"message": str(exception),
"stack_trace": traceback.format_exc(),
"service": os.environ.get("SERVICE_NAME", "unknown-service")
}
def is_service_degraded(error_info):
# 특정 에러 코드나 발생 빈도에 따라 복구 필요 여부 판단
return error_info.get("code") in ["TIMEOUT", "RESOURCE_EXHAUSTED"]
def attempt_auto_recovery(error_info):
print(f"Attempting auto-recovery for error: {error_info.get('code')}")
# 실제 복구 로직: 서비스 재시작, 설정 재로드 등
if error_info.get("code") == "TIMEOUT":
print("Restarting dependent service...")
# dependent_service.restart()
pass

마지막으로, 에러 발생 시점, 종류, 관련 요청 정보 등을 자동으로 수집하여 중앙 시스템에 저장하는 기능을 구축했습니다. 이를 통해 에러 패턴을 분석하고 선제적으로 대응할 수 있게 되었습니다.

# 에러 정보 중앙 시스템 로깅 (예시)
import requests
import json
def log_error_to_central_system(error_info):
central_logging_url = "http://your-central-logging-service.internal/log"
try:
response = requests.post(central_logging_url, json=error_info)
response.raise_for_status() # HTTP 오류 발생 시 예외 발생
print("Error logged to central system successfully.")
except requests.exceptions.RequestException as e:
print(f"Failed to log error to central system: {e}")

결과

• 사용자 경험이 크게 개선되어 에러 발생 시 혼란이 줄었습니다.
• 자동 복구 기능 덕분에 서비스 중단 시간이 감소했습니다.
• 체계적인 에러 정보 수집으로 문제 해결 속도가 향상되었습니다.

정리 — 같은 함정 안 빠지려면

• [ ] 에러 메시지는 사용자 친화적으로, 기술적인 내용은 최소화합니다.
• [ ] 에러 발생 시 자동으로 복구될 수 있는 시나리오를 미리 정의하고 구현합니다.
• [ ] 에러 발생 시점, 종류, 관련 정보 등을 상세하게 기록하고 중앙에서 관리할 수 있는 시스템을 구축합니다.
• [ ] 복구 로직 구현 시 발생할 수 있는 예외 상황을 충분히 고려하여 테스트합니다.