예외 처리와 로깅 전략 완벽 가이드

초급 개발자를 위한 예외 처리와 로깅 전략 가이드입니다. Try-Catch부터 Sentry까지, 실무에서 바로 적용할 수 있는 에러 관리 기법을 단계별로 설명합니다.

---

목차

1. Try-Catch 전략
2. 로깅 레벨 (DEBUG, INFO, WARN, ERROR)
3. 구조화된 로깅 (Structured Logging)
4. 에러 추적 시스템 (Sentry, Rollbar)
5. 스택 트레이스 관리
6. 운영 환경 에러 모니터링

---

1. Try-Catch 전략

어느 날 김개발 씨가 배포한 서비스에서 갑자기 장애가 발생했습니다. 화면이 하얗게 변하더니 아무것도 표시되지 않았습니다.

알고 보니 API 호출 실패를 제대로 처리하지 않아서 생긴 문제였습니다.

Try-Catch는 한마디로 프로그램이 넘어지려 할 때 받쳐주는 안전망입니다. 마치 서커스 공중그네 아래 펼쳐진 그물망처럼, 예상치 못한 에러가 발생해도 프로그램 전체가 멈추지 않도록 보호해줍니다.

이것을 제대로 활용하면 사용자에게 친절한 에러 메시지를 보여주고, 개발자는 문제의 원인을 정확히 파악할 수 있습니다.

다음 코드를 살펴봅시다.

// 사용자 정보를 가져오는 함수
async function fetchUserData(userId: string) {
  try {
    // API 호출 시도
    const response = await fetch(`/api/users/${userId}`);

    if (!response.ok) {
      // HTTP 에러 상태 처리
      throw new Error(`HTTP ${response.status}: 사용자 조회 실패`);
    }

    return await response.json();
  } catch (error) {
    // 에러 로깅 후 사용자 친화적 메시지 반환
    console.error('사용자 조회 중 오류:', error);
    throw new Error('사용자 정보를 불러올 수 없습니다');
  }
}

김개발 씨는 입사 3개월 차 주니어 개발자입니다. 첫 번째 기능 배포 후 뿌듯함도 잠시, 고객센터에서 연락이 왔습니다.

"화면이 하얗게 변해서 아무것도 안 보여요!" 급하게 로그를 확인해보니 외부 API 서버가 잠시 응답을 멈춘 것이 원인이었습니다. 문제는 김개발 씨의 코드가 이런 상황을 전혀 대비하지 않았다는 점입니다.

선배 개발자 박시니어 씨가 다가와 말했습니다. "개발 환경에서는 모든 게 완벽하게 돌아가죠.

하지만 실제 세상은 다릅니다. 네트워크가 끊기기도 하고, 서버가 느려지기도 하고, 예상치 못한 데이터가 들어오기도 해요." 그렇다면 Try-Catch란 정확히 무엇일까요?

쉽게 비유하자면, Try-Catch는 마치 놀이공원의 안전바와 같습니다. 롤러코스터가 아무리 급격하게 움직여도 안전바가 승객을 보호하듯이, Try 블록 안에서 아무리 심각한 에러가 발생해도 Catch 블록이 프로그램을 보호합니다.

Try-Catch가 없던 시절에는 어땠을까요? 에러가 발생하면 프로그램 전체가 멈춰버렸습니다.

사용자는 갑자기 흰 화면을 보게 되고, 개발자는 무엇이 문제인지 파악하기 어려웠습니다. Try 블록에는 에러가 발생할 수 있는 코드를 넣습니다.

API 호출, 파일 읽기, 데이터 파싱 같은 외부 요인에 의존하는 작업들이 여기에 해당합니다. Catch 블록은 Try에서 에러가 발생했을 때 실행됩니다.

여기서 에러를 로깅하고, 사용자에게 친절한 메시지를 보여주고, 필요하다면 대체 동작을 수행합니다. 위 코드를 살펴보면, 먼저 fetch 함수로 API를 호출합니다.

응답 상태가 정상이 아니면 직접 에러를 던집니다. Catch 블록에서는 원본 에러를 로깅한 후, 사용자가 이해할 수 있는 메시지로 변환하여 다시 던집니다.

실제 현업에서는 모든 API 호출, 데이터베이스 쿼리, 파일 처리에 Try-Catch를 적용합니다. 특히 사용자 입력을 처리하는 부분에서는 필수입니다.

주의할 점은 무분별한 Try-Catch 남용입니다. 모든 코드를 Try-Catch로 감싸면 오히려 진짜 버그를 숨기게 됩니다.

에러가 발생할 가능성이 있는 곳에만 전략적으로 사용해야 합니다. 다시 김개발 씨 이야기로 돌아가면, 박시니어 씨의 조언을 듣고 API 호출 부분에 Try-Catch를 추가했습니다.

이제 서버가 응답하지 않아도 "잠시 후 다시 시도해주세요"라는 친절한 메시지가 표시됩니다.

실전 팁

💡 - 에러가 발생할 가능성이 있는 외부 의존성 코드에만 Try-Catch를 적용하세요

• Catch에서 에러를 삼키지 말고, 반드시 로깅하거나 상위로 전파하세요

---

2. 로깅 레벨 (DEBUG, INFO, WARN, ERROR)

김개발 씨가 운영 서버 로그를 열어보니 수천 줄의 메시지가 빼곡히 쌓여 있었습니다. "여기서 어떻게 문제를 찾죠?" 박시니어 씨가 웃으며 말했습니다.

"로그도 계급이 있거든요."

로깅 레벨은 로그 메시지의 중요도를 구분하는 체계입니다. 마치 병원의 응급 분류 시스템처럼 DEBUG는 일반 진료, INFO는 정기 검진, WARN은 주의 관찰, ERROR는 응급 상황으로 나눕니다.

이렇게 분류하면 상황에 따라 필요한 정보만 빠르게 찾을 수 있습니다.

다음 코드를 살펴봅시다.

import winston from 'winston';

// 로거 설정
const logger = winston.createLogger({
  level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [new winston.transports.Console()]
});

// 사용 예시
logger.debug('변수 값 확인: userId = 123');      // 개발 시 디버깅용
logger.info('사용자 로그인 성공: user@email.com'); // 정상 이벤트
logger.warn('API 응답 지연: 3초 초과');           // 잠재적 문제
logger.error('결제 처리 실패: 카드 승인 거절');    // 즉각 대응 필요

김개발 씨는 버그를 추적하기 위해 여기저기 console.log를 심어두었습니다. 개발할 때는 편했지만, 운영 환경에서는 재앙이었습니다.

로그 파일이 하루 만에 수 기가바이트로 불어났습니다. 박시니어 씨가 로그 파일을 보며 한숨을 쉬었습니다.

"이건 마치 모든 대화를 녹음해둔 것과 같아요. 중요한 내용을 찾으려면 전부 다 들어봐야 하죠." 로깅 레벨이란 정확히 무엇일까요?

뉴스 방송을 생각해보세요. 속보가 있고, 주요 뉴스가 있고, 일반 뉴스가 있습니다.

대형 사건이 터지면 속보로 알려주지만, 동네 축제 소식까지 속보로 내보내진 않습니다. 로깅 레벨도 마찬가지입니다.

DEBUG는 가장 상세한 레벨입니다. 변수 값, 함수 호출 순서, 조건문 분기 등 개발자가 코드 흐름을 추적할 때 필요한 정보를 담습니다.

운영 환경에서는 보통 비활성화합니다. INFO는 정상적인 작동을 기록합니다.

사용자 로그인, 주문 완료, 배치 작업 시작과 종료 같은 이벤트입니다. "시스템이 잘 돌아가고 있다"는 증거가 됩니다.

WARN은 당장은 문제없지만 주의가 필요한 상황입니다. API 응답이 평소보다 느리거나, 메모리 사용량이 임계치에 근접할 때 경고를 남깁니다.

ERROR는 즉각적인 대응이 필요한 심각한 문제입니다. 결제 실패, 데이터베이스 연결 끊김, 인증 오류 등이 여기에 해당합니다.

위 코드에서 winston 라이브러리를 사용해 로거를 설정합니다. 운영 환경에서는 info 레벨 이상만, 개발 환경에서는 debug까지 모두 출력합니다.

실무에서는 환경에 따라 로깅 레벨을 조절합니다. 개발 중에는 DEBUG로 모든 것을 보고, 운영에서는 INFO 이상만 남깁니다.

문제가 발생하면 일시적으로 DEBUG를 켜서 상세 정보를 수집합니다. 주의할 점은 로깅 레벨을 일관성 있게 사용하는 것입니다.

팀 내에서 "어떤 상황에 어떤 레벨을 쓸지" 가이드라인을 정해두면 좋습니다. 김개발 씨는 이제 모든 console.log를 적절한 로깅 레벨로 교체했습니다.

운영 환경에서는 중요한 로그만 남기고, 버그 발생 시에는 DEBUG를 켜서 원인을 추적합니다.

실전 팁

💡 - 운영 환경에서는 INFO 이상만 남기고, DEBUG는 필요할 때만 켜세요

• 팀 내에서 로깅 레벨 사용 기준을 문서화하세요

---

3. 구조화된 로깅 (Structured Logging)

박시니어 씨가 로그 검색 화면을 보여주며 말했습니다. "userId가 12345인 사용자의 모든 활동을 찾아볼까요?" 클릭 한 번에 관련 로그가 쫙 정렬되어 나왔습니다.

김개발 씨는 놀라움을 감추지 못했습니다.

구조화된 로깅은 로그를 사람이 읽는 문장이 아닌 기계가 파싱할 수 있는 데이터 형태로 남기는 방식입니다. 마치 도서관에서 책을 제목순으로만 꽂아두는 것이 아니라, 저자, 출판년도, 장르별로 분류해두는 것과 같습니다.

검색과 분석이 훨씬 쉬워집니다.

다음 코드를 살펴봅시다.

import winston from 'winston';

const logger = winston.createLogger({
  format: winston.format.json(),
  transports: [new winston.transports.Console()]
});

// 구조화된 로깅 - 검색과 분석이 용이
logger.info('주문 생성 완료', {
  event: 'ORDER_CREATED',
  orderId: 'ORD-2024-001',
  userId: 'user_123',
  amount: 50000,
  items: 3,
  paymentMethod: 'card',
  duration: 245  // 처리 시간 (ms)
});

// 출력 결과 (JSON 형태)
// {"level":"info","message":"주문 생성 완료","event":"ORDER_CREATED",
//  "orderId":"ORD-2024-001","userId":"user_123","amount":50000,...}

김개발 씨의 이전 로그는 이랬습니다. "사용자 user_123이 상품 3개를 50000원에 주문했습니다." 사람이 읽기엔 좋지만, 5만 원 이상 주문만 찾고 싶을 때는 어떻게 해야 할까요?

박시니어 씨가 설명합니다. "문장형 로그는 마치 일기장과 같아요.

읽기는 좋지만 특정 정보를 찾으려면 전부 읽어야 하죠." 구조화된 로깅이란 무엇일까요? 엑셀 시트를 떠올려보세요.

각 열에 날짜, 사용자, 금액, 상품명이 정리되어 있으면 "금액이 5만 원 이상인 행"을 필터 한 번으로 찾을 수 있습니다. 구조화된 로깅은 로그를 이런 표 형태로 만드는 것입니다.

실제로는 JSON 형태로 저장합니다. 각 로그가 키-값 쌍으로 이루어진 객체가 됩니다.

이렇게 하면 로그 분석 도구가 자동으로 파싱하고 인덱싱할 수 있습니다. 위 코드를 보면 logger.info의 두 번째 인자로 객체를 전달합니다.

메시지는 사람을 위한 것이고, 객체는 기계를 위한 것입니다. event 필드로 로그 종류를 구분하고, 관련 데이터를 속성으로 첨부합니다.

실무에서는 Elasticsearch, Datadog, CloudWatch 같은 도구와 함께 사용합니다. 구조화된 로그는 이런 도구에서 쿼리와 대시보드 생성이 매우 쉽습니다.

예를 들어 "지난 1시간 동안 결제 금액이 100만 원 이상인 주문"을 찾는다고 해봅시다. 구조화된 로그라면 event:ORDER_CREATED AND amount:>=1000000 같은 쿼리로 순식간에 찾을 수 있습니다.

주의할 점은 민감한 정보입니다. 비밀번호, 카드번호, 주민등록번호 같은 정보는 절대 로그에 남기면 안 됩니다.

구조화된 로깅을 도입할 때 어떤 필드를 기록할지 가이드라인을 정해야 합니다. 김개발 씨는 모든 로그를 구조화된 형태로 변경했습니다.

이제 "어제 오류가 발생한 사용자들의 공통점이 뭘까?" 같은 질문에 데이터로 답할 수 있게 되었습니다.

실전 팁

💡 - 모든 로그에 공통 필드(timestamp, requestId, userId)를 포함하세요

• 민감한 정보는 마스킹하거나 아예 기록하지 마세요

---

4. 에러 추적 시스템 (Sentry, Rollbar)

새벽 3시, 김개발 씨의 휴대폰이 울렸습니다. Sentry에서 보낸 알림이었습니다.

"프로덕션에서 새로운 에러가 50건 발생했습니다." 잠에서 깬 김개발 씨는 노트북을 열어 즉시 문제를 확인했습니다.

에러 추적 시스템은 애플리케이션에서 발생하는 에러를 자동으로 수집하고 분석해주는 서비스입니다. 마치 CCTV가 사고 현장을 녹화해두는 것처럼, 에러 발생 순간의 모든 정보를 캡처합니다.

덕분에 사용자가 신고하기 전에 개발자가 먼저 문제를 발견할 수 있습니다.

다음 코드를 살펴봅시다.

import * as Sentry from '@sentry/node';

// Sentry 초기화
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,  // 성능 모니터링 샘플링
});

async function processPayment(orderId: string, userId: string) {
  try {
    // 결제 처리 로직
    const result = await paymentGateway.charge(orderId);
    return result;
  } catch (error) {
    // Sentry에 에러 전송 + 컨텍스트 정보 추가
    Sentry.captureException(error, {
      tags: { module: 'payment', orderId },
      user: { id: userId },
      extra: { timestamp: new Date().toISOString() }
    });
    throw error;
  }
}

예전에 김개발 씨는 에러를 어떻게 발견했을까요? 대부분 고객 문의를 통해서였습니다.

"결제가 안 돼요", "화면이 이상해요" 같은 연락을 받고 나서야 로그를 뒤지기 시작했습니다. 박시니어 씨가 말했습니다.

"고객이 문제를 알려줄 때까지 기다리는 건 마치 병원에 환자가 찾아올 때까지 의사가 가만히 앉아있는 것과 같아요. 우리가 먼저 찾아내야 합니다." 에러 추적 시스템이란 무엇일까요?

자동차의 블랙박스를 생각해보세요. 사고가 나면 그 순간의 영상, 속도, 충격량이 모두 기록됩니다.

에러 추적 시스템도 마찬가지입니다. 에러가 발생하면 스택 트레이스, 사용자 정보, 브라우저 환경, 발생 빈도까지 자동으로 수집합니다.

대표적인 서비스로 Sentry, Rollbar, Bugsnag이 있습니다. 이들은 에러를 그룹화하고, 비슷한 에러를 묶어주고, 발생 추이를 그래프로 보여줍니다.

위 코드에서 Sentry.captureException은 에러를 Sentry 서버로 전송합니다. tags로 분류 기준을 추가하고, user로 어떤 사용자에게 발생했는지, extra로 추가 정보를 첨부합니다.

실무에서 가장 유용한 기능은 알림입니다. 새로운 에러가 발생하거나 특정 에러가 급증하면 Slack, 이메일, SMS로 즉시 알려줍니다.

새벽에 장애가 발생해도 빠르게 대응할 수 있습니다. 또 다른 강점은 릴리즈 추적입니다.

어떤 배포 버전에서 에러가 발생했는지 알 수 있어서, 문제가 있는 배포를 빠르게 롤백할 수 있습니다. 주의할 점은 비용과 개인정보입니다.

에러가 너무 많이 발생하면 비용이 올라가고, 사용자 정보를 전송할 때는 개인정보보호법을 준수해야 합니다. 김개발 씨는 이제 Sentry 대시보드를 매일 아침 확인합니다.

고객이 문의하기 전에 문제를 발견하고 수정하는 일이 일상이 되었습니다.

실전 팁

💡 - 에러 알림을 Slack이나 Teams와 연동하여 팀 전체가 즉시 인지하도록 하세요

• 릴리즈 버전을 태깅하여 어떤 배포에서 문제가 생겼는지 추적하세요

---

5. 스택 트레이스 관리

김개발 씨가 에러 로그를 보며 멍해졌습니다. 화면에는 수십 줄의 파일 경로와 줄 번호가 빼곡했습니다.

"이게 다 뭐예요?" 박시니어 씨가 웃으며 말했습니다. "그건 에러가 남긴 발자국이에요."

스택 트레이스는 에러가 발생하기까지 코드가 어떤 경로로 실행되었는지 보여주는 기록입니다. 마치 등산로에서 길을 잃었을 때 지나온 발자국을 따라가면 어디서 잘못 들었는지 알 수 있듯이, 스택 트레이스를 읽으면 에러의 근본 원인을 찾을 수 있습니다.

다음 코드를 살펴봅시다.

class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public isOperational: boolean = true
  ) {
    super(message);
    this.name = this.constructor.name;
    // 스택 트레이스에서 이 생성자 호출을 제외
    Error.captureStackTrace(this, this.constructor);
  }
}

function handleError(error: Error) {
  // 스택 트레이스를 읽기 쉽게 파싱
  const stackLines = error.stack?.split('\n') || [];
  const relevantStack = stackLines
    .filter(line => line.includes('/src/'))  // 우리 코드만 필터링
    .slice(0, 5);  // 상위 5개만

  console.error('에러 발생:', error.message);
  console.error('호출 경로:', relevantStack.join('\n'));
}

김개발 씨가 처음 스택 트레이스를 봤을 때 외계어 같았습니다. at Object.fetchUser (/app/src/services/user.ts:45:12) 같은 줄이 수십 개 나열되어 있었습니다.

박시니어 씨가 천천히 설명을 시작했습니다. "스택 트레이스를 읽는 건 탐정이 범인을 추적하는 것과 같아요.

단서를 따라가면 진범을 찾을 수 있죠." 스택 트레이스란 정확히 무엇일까요? 프로그램이 실행되면 함수들이 차례로 호출됩니다.

A 함수가 B를 부르고, B가 C를 부릅니다. 이 호출 순서가 마치 접시를 쌓아올리듯 스택에 기록됩니다.

에러가 발생하면 이 스택을 출력한 것이 스택 트레이스입니다. 가장 위에 있는 줄이 에러가 실제로 발생한 위치입니다.

아래로 내려갈수록 그 함수를 호출한 상위 함수들이 나옵니다. 맨 아래는 프로그램의 시작점입니다.

위 코드에서 Error.captureStackTrace는 더 깔끔한 스택 트레이스를 만들어줍니다. 에러 클래스 생성자 호출 부분을 제외해서 실제 문제 지점만 보여줍니다.

handleError 함수에서는 스택 트레이스를 파싱합니다. node_modules 안의 라이브러리 코드는 보통 관심 대상이 아닙니다.

/src/ 경로가 포함된 우리 코드만 필터링하면 훨씬 읽기 쉬워집니다. 실무에서 스택 트레이스를 잘 관리하는 방법이 있습니다.

첫째, 커스텀 에러 클래스를 만들어 의미 있는 이름을 붙입니다. 둘째, 소스맵을 설정해서 번들된 코드가 아닌 원본 코드 위치를 보여줍니다.

주의할 점은 운영 환경에서 스택 트레이스 전체를 사용자에게 노출하면 안 된다는 것입니다. 보안에 취약할 수 있습니다.

로그에만 남기고 사용자에게는 친절한 메시지만 보여주세요. 김개발 씨는 이제 스택 트레이스를 두려워하지 않습니다.

오히려 에러의 원인을 찾는 가장 빠른 지도라고 생각합니다.

실전 팁

💡 - 소스맵을 설정하여 번들된 코드가 아닌 원본 코드 위치를 확인하세요

• 스택 트레이스 전체를 사용자에게 노출하지 말고 로그에만 기록하세요

---

6. 운영 환경 에러 모니터링

배포 버튼을 누른 후 김개발 씨는 초조하게 모니터를 바라봤습니다. 박시니어 씨가 옆에서 대시보드를 열며 말했습니다.

"긴장하지 마세요. 우리에겐 감시 시스템이 있으니까요."

운영 환경 에러 모니터링은 실제 서비스에서 발생하는 에러를 실시간으로 감시하는 체계입니다. 마치 건물의 보안 관제 시스템처럼 24시간 서비스를 지켜보며 이상 징후가 발견되면 즉시 알려줍니다.

배포 후 안심하고 잠들 수 있게 해주는 안전장치입니다.

다음 코드를 살펴봅시다.

import { logger } from './logger';
import * as Sentry from '@sentry/node';
import { metrics } from './metrics';

// 전역 에러 핸들러 설정
function setupErrorMonitoring() {
  // 처리되지 않은 예외 감지
  process.on('uncaughtException', (error) => {
    logger.error('처리되지 않은 예외 발생', { error: error.message });
    Sentry.captureException(error);
    metrics.increment('errors.uncaught');
    process.exit(1);  // 안전한 종료
  });

  // 처리되지 않은 Promise 거부 감지
  process.on('unhandledRejection', (reason) => {
    logger.error('처리되지 않은 Promise 거부', { reason });
    Sentry.captureException(reason);
    metrics.increment('errors.unhandled_rejection');
  });
}

// 헬스체크 엔드포인트
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: Date.now() });
});

김개발 씨에게 배포는 항상 두려운 일이었습니다. "혹시 내가 모르는 버그가 있으면 어떡하지?" 밤새 서버 로그를 새로고침하며 불안에 떨었습니다.

박시니어 씨가 말했습니다. "좋은 모니터링 시스템이 있으면 밤에 푹 잘 수 있어요.

문제가 생기면 시스템이 깨워줄 테니까요." 운영 환경 에러 모니터링이란 무엇일까요? 종합병원의 중환자실을 생각해보세요.

환자의 심박수, 혈압, 산소포화도가 모니터에 실시간으로 표시됩니다. 수치가 위험 범위에 들어가면 경보가 울립니다.

운영 환경 모니터링도 마찬가지로 서비스의 생체 신호를 감시합니다. 위 코드에서 uncaughtException은 처리되지 않은 예외를 잡습니다.

try-catch 없이 발생한 에러가 여기로 옵니다. 이런 에러는 심각한 문제이므로 로그를 남기고 프로세스를 안전하게 종료합니다.

unhandledRejection은 await 없이 실행된 Promise에서 발생한 에러입니다. 이 에러는 조용히 무시되기 쉬워서 특별히 감시해야 합니다.

헬스체크 엔드포인트는 서버가 살아있는지 확인하는 용도입니다. 로드밸런서나 쿠버네티스가 이 엔드포인트를 주기적으로 호출해서 서버 상태를 확인합니다.

실무에서는 여러 도구를 조합합니다. Sentry로 에러를 추적하고, Datadog이나 Grafana로 메트릭을 시각화하고, PagerDuty로 당직자에게 알림을 보냅니다.

핵심은 알림 피로를 피하는 것입니다. 모든 에러에 알림을 보내면 정작 중요한 알림을 놓칩니다.

에러율이 임계치를 넘거나 새로운 유형의 에러가 발생할 때만 알림을 보내도록 설정합니다. 또한 대시보드를 만들어 서비스 상태를 한눈에 볼 수 있게 합니다.

에러율, 응답시간, 활성 사용자 수 같은 핵심 지표를 실시간으로 표시합니다. 김개발 씨는 이제 배포 후에도 여유롭습니다.

Slack에 연동된 알림이 조용하면 서비스가 잘 돌아가고 있다는 뜻이니까요. 문제가 생기면 5분 안에 알림이 오고, 대시보드에서 원인을 파악할 수 있습니다.

실전 팁

💡 - 알림 임계치를 적절히 설정하여 알림 피로를 방지하세요

• 핵심 지표를 보여주는 대시보드를 만들어 팀 전체가 공유하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!