안녕하세요. 포스타입 프론트엔드 개발자 이준근입니다.

오류, 결함, 버그, 장애는 소프트웨어 개발과 밀접하게 연관된 용어입니다. 오류는 종종 결함으로 이어지며 결함이 해결되지 않으면 장애로 확산될 수 있습니다. 각각의 용어는 무엇을 의미할까요?

오류는 개발자가 코드 작성 중 잘못된 로직을 구현하거나 요구 사항을 오해하여 발생하는 상황입니다. 결함은 제품의 예상 동작과 실제 동작이 일치하지 않는 상황입니다. 테스터나 최종 사용자가 이를 발견하는 경우 일반적으로 버그라고 불립니다. 장애는 하나 이상의 버그로 인해 서비스가 중단되거나 주요 기능이 정상적으로 작동하지 않는 상황을 의미합니다.

오류, 결함, 장애

사람이 작업하는 한 오류 없는 개발은 불가능하기에 개발자는 최종 사용자가 장애를 겪지 않도록 오류를 조기에 발견하고 수정해야 합니다. 만약 장애가 발생했다면 상황을 신속히 파악하고 수정하여 사용자에게 미치는 영향을 최소화해야 합니다. 포스타입은 이를 위해 기존에 어떻게 모니터링을 진행해왔으며 왜 Sentry를 도입하게 되었을까요?

모니터링 시스템 개선의 필요성

기존에는 CloudWatch Logs와 유저 오류 문의를 통해 장애를 감지하고 수정하는 방식으로 에러에 대응했습니다. CloudWatch Logs는 AWS에서 제공하는 서비스로 애플리케이션 로그 데이터를 실시간으로 수집하고 모니터링 할 수 있는 기능을 제공합니다. 이를 통해 발생 빈도가 높은 오류를 모니터링하거나 특정 예외 발생을 추적하고 수집된 로그 데이터를 바탕으로 세부 사항을 파악하여 문제를 해결할 수 있었습니다. 하지만 어떤 유형의 유저가 에러를 겪었는지, 어떤 작업 흐름에서 발생했는지, 어떤 환경에서 발생했는지를 추적하는 데는 한계가 있었습니다. 

유저 오류 문의는 유저가 문제를 인지하지 못하거나 디버깅에 필요한 정보가 부족한 경우가 많아 장애의 원인 파악과 대응이 지연되는 경우가 발생했습니다. 초기에는 큰 문제 없었지만 서비스가 확장되고 개발자 수가 증가하면서 기존 방식의 한계가 드러났고, 에러 모니터링 시스템 개선이 필요하다고 판단하여 Sentry를 도입했습니다.

https://sentry.io

Sentry는 애플리케이션의 에러를 실시간으로 감지하고 에러 발생 위치, 유저 환경 및 행동 흐름에 따른 에러 발생 경위 등 상세한 정보를 제공하는 모니터링 플랫폼입니다. 이를 통해 기존 모니터링 방식에서 발생했던 문제들을 개선할 수 있었습니다. 그러나 도입 초기에는 예상과 달리 모니터링이 쉽지 않았고 활용 빈도가 점차 줄어드는 상황이 발생했습니다. 실시간으로 감지된 에러를 슬랙 채널에 자동으로 리포팅 되도록 연동했음에도 불구하고 해당 채널을 모니터링하는 사람이 없어졌습니다. 그 원인은 무엇일까요?

초기 도입 시의 문제 및 개선 방안

초기 도입 시 발생한 문제

에러의 종류와 수가 너무 많아 관리가 어려웠습니다. 슬랙 채널로 실시간으로 쌓이는 무수한 알림 속에는 해결해야 할 중요한 에러도 있었고, 애플리케이션과 무관한 에러도 포함되어 있었기 때문에 이를 구별하는데 어려움이 있었고 우선순위를 매기기도 힘들었습니다. API 에러의 경우에는 분석을 위해 요청 값, 응답 값, 헤더, 쿠키 등 추가적인 디버깅 정보가 필요했지만 Sentry는 이를 기본적으로 제공되지 않아 CloudWatch Logs를 별도로 확인해야만 했습니다.

에러의 유형과 중요도가 한눈에 파악되지 않는 상황

개선 방안

핵심 원인은 수집할 에러 범위와 유형을 명확히 정의하지 않았고 각 에러 유형별로 분석에 필요한 정보를 고려하지 않은 점에 있었습니다. 문제를 해결하기 위해 주요 개선 사항을 도출하고 각 개선 사항을 어떻게 해결할지 고민했습니다.

1. 에러 수집 대상 정의

애플리케이션의 장애를 최소화하기 위해 Sentry를 도입하였기에 장애를 유발할 수 있는 주요 에러 유형에 집중하고자 했습니다. Sentry에 수집된 에러와 과거 장애 사례를 비교한 결과, 주요 원인은 서버 API 에러와 React 렌더링 에러로 확인되었습니다. 이에 두 에러를 중점적으로 관리하기로 결정했습니다.

더 나아가 API 에러 중에서는 500번 대 에러만 수집하기로 결정했습니다. Sentry에 수집된 400번 대 에러를 분석한 결과 대부분 사용자의 입력 오류나 의도된 클라이언트 요청 실패로 발생한 것이었으며 서비스 장애로 이어질 가능성이 낮았기 때문입니다. 주요 예시는 다음과 같습니다.

  • 폼 유효성 검사 실패: 필수 입력란을 채우지 않고 제출한 경우
  • 비로그인 사용자 접근: 로그인하지 않은 사용자가 로그인 필요 기능을 시도한 경우
  • 제한된 리소스 접근 시도: 잠긴 계정으로 로그인 시도, 사용 제한된 리소스 접근을 시도한 경우
2. 데이터 수집 및 에러 분류 기준 강화

먼저 공식문서를 통해 활용 가능한 기능들을 파악했습니다. API 에러 디버깅에 필요한 요청 값과 응답 값 등의 정보는 기본적으로 제공되지 않지만 Sentry의 추가 기능을 활용하면 이를 수집할 수 있다는 점을 확인했습니다. 또한 에러 식별과 Sentry 콘솔에서의 검색에 유용한 태그 기능, 원하는 이벤트만 선택적으로 수집할 수 있는 필터링 기능을 활용하여 수집 대상으로 정의한 에러만 선별적으로 수집하고 분류할 수 있다는 점도 확인했습니다.

3. 알람 기준 세분화

Sentry 콘솔에서 다양한 규칙을 만들고 관리할 수 있습니다. 예를 들어 새로운 이슈가 생성되거나 동일한 이슈가 반복적으로 발생하는 경우 등에 대해 세부적으로 설정할 수 있습니다. 이를 통해 기존에 문제가 되었던 과도한 알림을 제거하고 중요 알림만 슬랙 채널로 전달되도록 알림 규칙을 설정하고자 하였습니다.

문제 해결 과정

네트워크 요청 400번 대 에러 수집 제외

저희 팀은 HTTP 클라이언트 라이브러리로 Axios를 사용하고 있습니다. Axios는 요청과 응답을 가로챌 수 있는 인터셉터 기능을 제공합니다. 이를 활용해 400번 대 에러는 필터링하고, 500번 대 에러만 Sentry로 전송하는 로직을 구현했습니다.

// 응답 인터셉터
apiClient.interceptors.response.use(
  (response) => {
    // 2xx 응답은 그대로 반환
    return response;
  },
  (error) => {
    if (
      error.response &&
      error.response.status >= 500 &&
      error.response.status < 600
    ) {
      // 5xx 에러만 Sentry로 전송
      Sentry.captureException(error);
    }
    return Promise.reject(error);
  },
);

추가로 고려해야 했던 부분은 500번 대 에러 중 일부가 의도적으로 발생할 수 있다는 점과 서버 오류의 유형이 다양하다는 점이었습니다. 저희 팀은 공통 에러 응답 클래스를 사용하여, 응답 코드에 따라 에러를 세분화하고 구분할 수 있었습니다.

React 렌더링 에러 수집

React 렌더링 에러를 수집하기 위해 Error Boundary를 사용했습니다. Error Boundary는 하위 컴포넌트 트리에서 발생하는 자바스크립트 에러를 선언적으로 처리하는 컴포넌트입니다. Next.js에서는 global-error.tsx와 error.tsx 파일을 사용하여 Error Boundary를 구현할 수 있습니다. 아래는 Error Boundary에 Sentry 로그를 추가한 예시 코드입니다.

"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

Sentry는 Next.js에서 전체 애플리케이션의 에러를 수집하기 위해 global-error.tsx 파일을 사용하는 방법을 권장하지만 v14.0.5-canary.53 미만 버전에서는 global-error.tsx가 Root Layout에서 발생한 에러를 포착하지 못하는 문제가 있습니다. 현재 Next.js 13 버전을 사용하고 있어 이를 error.tsx 파일로 대체하였습니다. 또한 공식문서에 따르면 Next.js 15 및 @sentry/nextjs v8.28.0 미만 버전에서는 중첩된 서버 컴포넌트에서 발생한 에러를 Sentry가 수집할 수 없다고 명시되어 있습니다. 이 경우 컴포넌트 코드를 try...catch 로 감싸고 Sentry SDK에서 제공하는 captureException() 메소드를 사용하여 이벤트를 포착할 수 있었습니다.

API 관련 데이터 수집 강화

Sentry의 통합 기능을 사용하면 Sentry SDK의 기능을 확장할 수 있습니다. 기본적으로 적용되는 HTTP 관련 통합 기능은 다음과 같습니다.

  • Http Integration: HTTP 요청에 대한 spans 및 breadcrumbs를 기록
  • HttpContext Integration: URL, user-agent, referrer, headers 등의 HTTP 요청 정보를 첨부

추가로 적용할 수 있는 HTTP Client Integration은 브라우저 환경에서 fetch 또는 xhr 요청이 실패하면 해당 요청과 응답 정보를 자동으로 수집합니다. 또한 Sentry 설정 파일에서 sendDefaultPii 옵션을 활성화하면 에러 이벤트 발생 시 헤더와 쿠키 데이터를 함께 전송할 수 있습니다.

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  integrations: [Sentry.httpClientIntegration()],

  // 이 옵션은 헤더와 쿠키를 캡처하는 데 필요합니다.
  sendDefaultPii: true,
});

다만 Next.js를 사용할 경우 HTTP Client Integration은 브라우저 환경에서만 동작하므로 서버 컴포넌트에서 발생한 fetch 요청 정보를 자동으로 수집할 수 없습니다. 이를 해결하기 위해 Sentry의 Context 기능을 활용하여 이벤트에 임의의 데이터를 첨부해 전송할 수 있었습니다. 다음은 코드 예시입니다.

// API 에러 캡처 함수
const captureApiError = (axiosError: AxiosError) => {
  const {
    method,
    url,
    params,
    data: requestData,
    headers: requestHeaders,
  } = axiosError.config || {};
  const {
    status,
    statusText,
    data: responseData,
    headers: responseHeaders,
  } = axiosError.response || {};

  Sentry.withScope((scope) => {
    scope.setContext("요청", {
      method,
      url,
      params,
      requestData,
      requestHeaders,
    });
    scope.setContext("응답", {
      status,
      statusText,
      responseData,
      responseHeaders,
    });
    Sentry.captureException(axiosError); // Sentry로 에러 전송
  });
};

// 응답 인터셉터
apiClient.interceptors.response.use(
  (response) => {
    // 2xx 응답은 그대로 반환
    return response;
  },
  (error) => {
    if (
      error.response &&
      error.response.status >= 500 &&
      error.response.status < 600
    ) {
      // 5xx 에러만 Sentry로 전송
      captureApiError(error); // captureApiError 함수로 처리
    }
    return Promise.reject(error);
  },
);

추가로 고려해야 했던 부분은 Context 객체의 8KB 용량 제한이었습니다. 이에 따라 대용량 데이터를 전송해야 할 경우 Context를 분리하거나 일부 데이터 유실을 감수해야 했습니다. 또한 유저의 개인 정보 보호를 위해 민감한 필드에 데이터 스크러빙을 적용했습니다.

에러 분류 및 필터링

사용자 정의 태그

Sentry에서는 setTags() 메소드를 사용해 특정 이벤트에 사용자 정의 태그를 추가함으로써 에러를 더 쉽게 분류하고 필터링할 수 있습니다. Sentry 로깅 함수를 작성하고 setTags()를 사용해 사용자 정의 태그를 추가하여 수집 대상을 분류했습니다. 다음은 코드 예시입니다.

import * as Sentry from "@sentry/nextjs";

// API 에러 캡처 함수
export function captureApiError(error: Error) {
  Sentry.withScope(function (scope) {
    scope.setTags({
      is_custom_event: true,
    });

    /* 중간 로직 생략 */

    Sentry.captureException(error);
  });
}

// 렌더링 에러 캡처 함수
export function captureRenderError(error: Error) {
  Sentry.withScope(function (scope) {
    scope.setTags({
      is_custom_event: true,
    });

    /* 중간 로직 생략 */

    Sentry.captureException(error);
  });
}
보내기 전에

beforeSend는 Sentry에서 에러 이벤트가 전송되기 전에 해당 이벤트를 수정하거나 필터링할 수 있는 기능입니다. 이를 활용하면 특정 조건에 맞는 이벤트만 전송하거나 추가적인 처리 작업을 수행할 수 있습니다. 이 방식으로 사용자 정의 태그가 포함된 에러만 필터링하고 수집 대상 에러만 전송할 수 있었습니다.

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,

  beforeSend(event) {
    // is_custom_event 태그가 있는 경우에만 이벤트를 전송
    if (event.tags && event.tags.is_custom_event) {
      return event;
    }

    // is_custom_event 태그가 없으면 이벤트 전송하지 않음
    return null;
  },
});

마치며

프론트엔드 에러 모니터링 강화를 위해 Sentry를 도입했지만 초기에는 효과적으로 활용하는 데 어려움이 있었습니다. 이를 해결하기 위해 원인을 분석하고 개선을 위한 구체적인 방법을 연구하며 문제를 해결할 수 있었습니다. Sentry는 지속적으로 개선되고 있으며 현재는 GitHub와 Jira 연동을 통해 워크플로우를 최적화하고 알림 임계값을 모범 사례에 맞게 조정하고 있습니다.

주요 유형으로 정의한 에러만 수집
API 에러의 상세한 정보 수집

Sentry 도입을 통해 API 애플리케이션 에러뿐만 아니라 브라우저 호환성 문제, Google 번역 플러그인과 React 충돌, 인앱 브라우저 기능 장애 등 재현이 어렵고 탐지하기 까다로운 오류들도 빠르게 탐지하고 대응할 수 있었습니다. 모니터링 시스템 도입을 고민 중이시라면 빠르게 시도해볼 수 있는 Sentry를 추천드립니다.

참고


업무의 개선점을 찾고 적극적으로 개선하며 성장하는 포스타입의 문화에 관심있으신 분들은 아래 링크를 확인해 주세요.

감사합니다.

- 이 포스트는 25년 3월 기준으로 작성된 내용을 담고 있습니다 -

창작에 수익을 더하다, 크리에이터를 위한 슈퍼 앱 포스타입

포스타입님의 창작활동을 응원하고 싶으세요?