운영 환경에서 소스맵 적용으로 Sentry 오류 추적 개선하기

2025-02-25

프로덕션 환경에서 Sentry를 통한 효율적인 오류 추적을 위해 소스맵을 구성하는 방법을 설명합니다.

혹시 Sentry 에서도 소스 맵을 지원한다는 것을 알고계시나요?

Sentry는 에러 발생 시점의 정보를 수집하고 상세한 에러 보고서를 제공하여 효율적인 디버깅을 가능하게 합니다.

그러나 기본적으로 Sentry에 표시되는 코드는 Uglify된 상태입니다. 비록 에러에 대한 다양한 정보를 제공해주지만, 개발자들은 Uglify된 코드를 해석하여 실제 발생 지점을 다시 찾아내는 데 추가적인 시간을 소모하게 됩니다.

이러한 비효율적인 디버깅 플로우를 해결하기 위해 Sentry 에서는 소스 맵을 Sentry로 업로드할 수 있도록 지원하고 있습니다.

소스 맵 업로드 구성 방법은 크게 세 가지로 아래와 같습니다.

Sentry Wizard를 통한 소스 맵 업로드
번들러 또는 빌드 도구 수동 설정을 통한 소스 맵 업로드
Sentry CLI를 통한 소스 맵 업로드

이번 글에서는 Sentry Wizard와 번들러 또는 빌드 도구를 통한 소스 맵 업로드 방식을 다룹니다.

Sentry Wizard를 통한 소스 맵 적용

가장 간단한 방법으로, Sentry Wizard를 사용하는 것입니다.

아래의 명령어를 실행하면, Sentry 연동부터 패키지 설치, 빌드 도구 설정 등이 자동으로 진행됩니다.

npx @sentry/wizard@latest -i sourcemaps

번들러 또는 빌드 도구를 통해 소스 맵 수동 업로드

Sentry 에서 지원하는 대표적인 번들러 또는 빌드 도구로 webpack, rollup, vite 등이 있습니다. (Sentry 번들러 지원)

번들러를 통한 소스 맵 업로드는 현업에서 다양한 환경에 따라 분기 처리할 수 있기 때문에 매우 유용합니다.

보통 개발 환경에서는 개발중에도 배포가 진행되고, 반영 주기가 잦기 때문에 그에 따른 추가 비용이 발생하여 설정을 꺼놓는 경우가 있습니다. 이 외에도 브랜치별 도메인 분리로 Sentry를 사용하지 않는 도메인 같은 경우 예외적으로 번들러를 통해 소스 맵 생성과 업로드를 제어할 수 있습니다.

번들러 또는 빌드 도구에서 Sentry 소스맵을 적용하기 위해선 Sentry 에서 제공하는 플러그인을 통해 설정할 수 있습니다.

1. Sentry Auth Token 발급

Sentry 에 수동으로 소스 맵을 업로드하기 위해선 인증 토큰 발급이 필요합니다.

Sentry.io 접속 > Settings > Developer Settings 섹션 > Auth Tokens 메뉴

2. Sentry 플러그인 설치

해당 포스팅은 webpack 기준으로 작성되었습니다.

프로젝트에 Sentry 에서 제공하는 플러그인을 설치합니다.

npm i @sentry/webpack-plugin --save-dev

3. Sentry 플러그인 설정

소스 맵 수동 업로드 전 실제 빌드 시점에 소스 맵이 생성되고, 생성된 소스 맵은 Sentry 플러그인의 소스 맵 설정에 따라 업로드 후 제거됩니다.

❗️ 소스 맵 생성과 제거 로직은 함께 제어되어야하는 부분에 주의해주세요.

소스 맵이 제거가 진행되지 않았다면 운영 환경에 이미 모든 코드가 노출된 상태입니다.

// webpack.config.js
const { sentryWebpackPlugin } = require('@sentry/webpack-plugin')

const isProd = settings.SERVER !== 'development'

const webpackConfig = {
  devtool: isProd ? 'source-map' : false,
  ... // 그 외 설정
}

if (isProd) {
  webpackConfig.plugins.push(
    sentryWebpackPlugin({
      // 조직명
      org: settings.SENTRY_ORG,
      // 프로젝트명
      project: settings.SENTRY_PROJECT,
      // // Sentry 에서 발급 받은 인증 토큰
      authToken: settings.SENTRY_AUTH_TOKEN,
      // 소스맵 설정
      sourcemaps: {
        // 소스맵 파일 업로드 후 삭제할 파일 패턴
        filesToDeleteAfterUpload: '**/**/*.map',
        ignore: ['node_modules'],
      },
    })
  )
}

소스 맵 업로드 시 주의해야될 점

1. 소스 맵 업로드 과정 훑어보기

소스 맵이 정상적으로 업로드되지 않았을 경우를 위해 실제 빌드 시 소스 맵이 어떻게 업로드되는 지 알아야합니다.

빌드 실행
소스 맵 생성
Sentry에 소스 맵 업로드
업로드 후 소스 맵 파일 제거
빌드 완료

위의 과정을 통해 Sentry에 소스 맵이 업로드되고, 업로드 후에는 소스 맵이 안전하게 제거됩니다.

2. 소스 맵 생성과 Sentry 업로드는 동일한 조건으로 실행되어야 한다

위에서 소스 맵 생성과 Sentry 업로드는 동일한 조건으로 제어되어야한다고 말씀드렸습니다.

소스 맵 생성이 되지 않는 경우는 위와 같이 Sentry 업로드 시 파일을 찾을 수 없다는 오류가 발생합니다.

플러그인을 통해 Sentry 업로드가 되지 않을 경우 더 최악의 상황이 발생할 수 있습니다.

소스 맵 생성
소스 맵 생성과 조건이 달라 Sentry 업로드 로직이 실행되지 않음 (😱)
소스 맵 파일이 제거되지 않은 채 빌드 완료

동일한 변수로 또는 필드로 소스 맵 생성과 Sentry 업로드 로직을 제어해야합니다.

한 프로젝트안에 여러 환경이 존재하는 경우 피처 플래그 방식을 통해 안전하게 제어할 수 있습니다.

소스 맵 적용 전 / 소스 맵 적용 후

마무리

소스 맵이 실서비스에 업로드되게 되면 코드가 사용자에게 공개되어 취약점 분석을 통한 공격이나 인증 토큰 탈취 등 큰 보안 문제가 발생할 수 있습니다. 그렇기 때문에 반드시 Sentry 로 소스맵 업로드 후 제거되었는 지 환경별로 확인해야 합니다.

이번 Sentry 소스맵 업로드 작업은 소소해 보이지만, 이런 개선이 팀의 효율성을 크게 높이면서도, 적절한 주의와 테스트를 통해 보안 위험을 최소화할 수 있다는 점이 인상적이었습니다. :)

앞으로도 이런 작은 개선들을 통해 개발 환경과 프로세스를 지속적으로 발전시켜 나가려고 합니다.