사내 보안 리소스 통합 플랫폼 구축기 : 6. on-premise sentry 고도화

이전글 에서 sentry를 프론트엔드 서버에 연동 완료하였다. 하지만 어떤 유저가 발생한 오류인지 확인하기는 어려웠고 소스맵 연동도 제대로 되어있지 않아서 어떤 코드에서 발생한 에러인지 한 눈에 알아볼 수 없는 상황에 오류를 트레이스하기 어려운 문제점을 가지고 있었다.

 

또한, 현재 서비스가 릴리즈 되어있는 현재 시점에 사용자가 어떤 페이지(기능단위의 페이지로 구성되어 있다.)를 자주 들어가는지 알 수 있는 방법이 있으면 좋겠다는 내부의 의견도 존재했다. 그래서 나는 3가지에 대해서 일단 고도화를 진행하였다. 

 

1. 어떤 사용자로부터 비롯된 오류인가

2. 어떤 소스코드로부터 트레이스 된 오류인가

3. 어떤 페이지를 사용자가 많이 접근하는가

 

 

어떤 사용자로부터 비롯된 오류인가

Sentry에서는 에러 이벤트에 사용자 정보(Context) 를 함께 붙여서 전송할 수 있다.
가장 기본이 되는 API가 바로 setUser이다.

 

import * as Sentry from '@sentry/browser'; // 또는 @sentry/nextjs, @sentry/react 등

// 로그인 직후 혹은 유저 정보가 준비된 시점
Sentry.setUser({
  id: user.id,          // 내부 유저 ID
  email: user.email,    // (선택) 이메일
  username: user.name,  // (선택) 이름/닉네임
});

 

왼 : 적용 전, 오 : 적용 후

해당 Context로 어떤 유저에게서 발생한건지,

특정 사용자에게서만 발생하는 건지 등 오류 역추적에 도움을 줄 수 있게 되었다.

 

 

 

어떤 소스코드로부터 트레이스 된 오류인가

1. React Component Name 추적

이 페이지에서 사용된 어떤 React 컴포넌트에서 문제가 터진 건지, 그 컴포넌트가 어떤 부모 컴포넌트 트리 안에 있었는지 추적하는 것도 sentry에서 기능을 제공한다.

 

 

React Component Annotation 을 제공하고 있고, Next.js용 Sentry SDK에서는 reactComponentAnnotation 옵션으로 활성화할 수 있다.

 

https://docs.sentry.io/platforms/javascript/guides/react/features/component-names/

 

적용 방법

Next.js의 withSentryConfig 호출부에서 옵션만 켜주면 된다.

// next.config.js

const { withSentryConfig } = require('@sentry/nextjs');

const nextConfig = {
  // ... 기존 설정
};

module.exports = withSentryConfig(
  nextConfig,
  {
    // Sentry Webpack Plugin 옵션
    reactComponentAnnotation: {
      enabled: true,
    },
    // ... 그 밖의 옵션
  },
);

 

 

 

 

2. Source Map 지원

 

프론트엔드 코드는 빌드 과정에서 번들링/압축이 이루어지기 때문에, Sentry에 바로 연동하면 스택 트레이스에 대략 다음과 같이 표시된다.

• app-1234abcd.js:1:12345
• vendor-9876efgh.js:1:67890

이 정보만으로는 어떤 파일의 몇 번째 줄에서 에러가 발생했는지 알기 어렵다. 이 문제를 해결하기 위해 Source Map 지원을 추가했다.

Source Map 지원을 하게 되면 빌드된 JS 코드가 아닌 원본 코드 기준의 에러 위치 추적 가능하다.

소스맵이 연동되지 않은 상태

초기에 오류를 발생 시키면 다음과 같이 path가 트레이스 되어 어디에서 오류가 난 것인지 알 수 없다. 정확한 위치를 알기는 어렵다.

 

 

적용 방법 - 대부분 근본적으로 사용하는 방법

// next.config.js
const { withSentryConfig } = require('@sentry/nextjs');

module.exports = withSentryConfig(
  nextConfig,
  {
    // Upload a larger set of source maps for prettier stack traces (increases build time)
    widenClientFileUpload: true,
  },
);

 

 

 

 

나의 적용 방법

아쉽게도.. 나의 경우 해당 config 옵션을 켜는 것으로 연동이 되지 않았다...

Saas 버전이 아니라서 그런지는 모르겠으나,,,  다른 방안들을 찾아서 적용하였다.

 

 

일단 위에 소스맵이 연동되지 않은 사진에서 보이는 unminify code 버튼을 클릭했을 때 다음과 같은 오류를 마주했다.

Missing source file with a matching Debug ID
No Artifacts With Debug IDs Uploaded

 

문제 원인

번들에는 Debug ID가 있는데, 그 Debug ID와 매칭되는 소스맵이 sentry에 업로드가 되지 않아 발생한 것으로 보인다.

 

해결 포인트

빌드 시점에 Sentry Webpack 플러그인이 실행되어 Debug ID를 주입하고 업로드 시킨다.

 

나의 노션 기록..

Debug ID 매칭과 파일 업로드에 대해 다양한 시도들을 했었다...

토글을 펼쳐서 저 내용들을 다 정리하기엔.. 너무나 방대해서.... 결론적인 해결 방법에 대해서만 정리해보려 한다.

 

 

 

on-Premise 환경의 sentry에서 sourcemap 연동한 방법

 

1. sentryWebpackPlugin 설치

https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/webpack/#manual-setup

Webpack | Sentry for JavaScript

# npm
npm install @sentry/webpack-plugin --save-dev

# yarn
yarn add @sentry/webpack-plugin --dev

# pnpm
pnpm add @sentry/webpack-plugin --save-dev

sentryWebpackPlugin을 설치해준다.

 

2. next.config.js 설정하기

여기서 포인트는 productionBrowserSourceMaps 옵션을 true로 설정 후, sentryWebpackPlugin을 통해 소스맵을 생성하여 업로드 하는 것이다.

productionBrowserSourceMaps는 무엇인가?
- next.js 공식 문서
Next.js는 프로덕션 빌드 중에 브라우저 소스 맵 생성을 활성화할 수 있는 구성 플래그를 제공한다.
productionBrowserSourceMaps 옵션이 활성화되면 소스 맵은 JavaScript 파일과 동일한 디렉토리에 출력된다.

소스맵에 대한 정보를 제공하는 반면에 다음과 같은 trade off가 발생하니 참고할 것!
- 소스 맵을 추가하면 next build 시간이 증가할 수 있다.
- next build 중 메모리 사용량이 증가한다.

 

import { withSentryConfig } from '@sentry/nextjs';
import type { NextConfig } from 'next';
import { sentryWebpackPlugin } from '@sentry/webpack-plugin';

const isProd = process.env.NODE_ENV === 'production';

const nextConfig: NextConfig = {

	... next 설정
  
  // SOURCE MAP 생성을 위한 소스맵 생성
  productionBrowserSourceMaps: true,

  webpack(config, { isServer }) {
    if (!isServer) {
      config.devtool = 'source-map';
    }
    if (isProd) {
      config.plugins.push(
        sentryWebpackPlugin({
          org: process.env.NEXT_PUBLIC_SENTRY_ORG,
          project: process.env.NEXT_PUBLIC_SENTRY_PROJECT,
          url: process.env.NEXT_PUBLIC_SENTRY_URL,
          authToken: process.env.SENTRY_AUTH_TOKEN,

          sourcemaps: {
            assets: [
              '.next/static/chunks/**/*.{js,map}',
              '.next/static/css/**/*.{js,map}',
              '.next/server/**/*.{js,map}',
            ],
            ignore: [
              '**/node_modules/**',
              '**/*.br',
              '**/*.gz',
              '**/*.txt',
              '**/*.html',
              '**/*.wasm',
              '**/*.ts',
              '**/*.tsx',
              '**/*.json',
              '**/*.png',
              '**/*.jpg',
              '**/*.svg',
              '**/*.webp',
              '**/*.css.map',
            ],
          },
        }),
      );
    }

    return config;
  },
};

// Production 환경에서만 Sentry 설정 적용
const config =
  process.env.NODE_ENV === 'production'
    ? withSentryConfig(nextConfig, {
        org: process.env.NEXT_PUBLIC_SENTRY_ORG,
        project: process.env.NEXT_PUBLIC_SENTRY_PROJECT,
        sentryUrl: process.env.NEXT_PUBLIC_SENTRY_URL,
        authToken: process.env.SENTRY_AUTH_TOKEN,

        silent: !process.env.CI,
        disableLogger: true,
        automaticVercelMonitors: true,
        reactComponentAnnotation: {
          enabled: true,
        },
      })
    : nextConfig;

export default config;

 

 

⛰️ 소스맵 업로드 중 발생할 수 있는 문제 (feat. status 413 - Content Too Large)

HTTP 413 Content Too Large 응답 상태 코드는 요청 엔터티가 서버에 의해 정의된 제한보다 크다는 것을 나타낸다. 서버는 연결을 닫거나 Retry-After 헤더 필드를 반환할 수 있다.

 

해결 방법은 bodySize와 time out을 늘리는 방법이다.

nginx서버 기준으로 client_max_body_size와 proxy_read_timeout, proxy_send_timeout을 지정하여 해결했다.

 

우리 서버의 경우 nginx 기반이었는데 호스트 서버의 nginx.conf와 sentry server의 docker compose에 작성된 nginx.conf 설정을 다음과 같이 바꾸어 이를 해결하였다.

# host server의 nginx.conf

# sentry
  server {
      listen       9000 ssl;
      server_name  localhost;
      
      
      # 413 에러를 수정하기 위해 추가 필요
      client_max_body_size 200m;
      proxy_read_timeout 300s; 
      proxy_send_timeout 300s;

    ... 다른 설정들
  }

 

	///self-hosted sentry docker compose nginx.conf
	upstream relay {
		server relay:3000;
		keepalive 2;
	}

	upstream sentry {
		server web:9000;
		keepalive 2;
	}
	
	server {
		listen 80;
		
      # 413 에러를 수정하기 위해 추가 필요
      client_max_body_size 200m;
      proxy_read_timeout 300s; 
      proxy_send_timeout 300s;

		location /api/store/ {
			proxy_pass http://relay;
		}
		location ~ ^/api/[1-9]\d*/ {
			proxy_pass http://relay;
		}
		location ^~ /api/0/relays/ {
			proxy_pass http://relay;
		}
		location ^~ /js-sdk/ {
			root /var/www/;
			# This value is set to mimic the behavior of the upstream Sentry CDN. For security reasons,
			# it is recommended to change this to your Sentry URL (in most cases same as system.url-prefix).
			add_header Access-Control-Allow-Origin *;
		}
		location / {
			proxy_pass http://sentry;
		}
		location /_assets/ {
			proxy_pass http://sentry/_static/dist/sentry/;
			proxy_hide_header Content-Disposition;
		}
		location /_static/ {
			proxy_pass http://sentry;
			proxy_hide_header Content-Disposition;
		}
	}

 

적용 결과

소스맵 연동을 통해 어떤 코드에서 에러를 던진건지 한눈에 확인이 가능해졌다. 번들 파일 이름 대신
src/components/ReferenceList.tsx:45, src/pages/reference/[id].tsx:120 형태로 원본 파일 + 라인 번호가 나온다.

IDE에서 해당 파일/라인을 바로 열어볼 수 있기 때문에, 에러 분석 속도가 눈에 띄게 빨라졌다.

 

 

어떤 페이지를 사용자가 많이 접근하는가

 

* metrics 데이터 커스텀
Saas에서는 기본적으로 제공하는 기능이나, 현재 설치 된 on-premise 버전에서는 metrics를 지원하지 않았다.

이벤트 message 기반으로 로그 데이터 필터링을 통해 metrics 확인하여 모니터링 로그 고도화 예정이다.

 

 

원래 Sentry는 “에러 모니터링”에 초점이 맞춰진 도구다.
다만, 우리 서비스 특성상 유입량이 크지 않고 기능 단위 페이지 구조라서, 가벼운 수준의 “페이지 접근 통계”는 Sentry만으로도 충분히 확인할 수 있다고 판단했다. 나는 두 가지 정보에 집중했다.

1. 어떤 페이지에서 에러가 많이 발생하는가?
2. 사용자들이 페이지를 얼마나 자주 방문하는가?

이를 위해 페이지 이동 시점에 Sentry 태그와 메시지를 함께 남기는 방식으로 구현했다. (한시적으로만 운영 후 제거 예정이다!)

 

코드 적용

“지금 실제 서비스에서 어떤 페이지를 많이 보고, 어떤 모달/기능이 자주 열리는지 대략이라도 알고 싶다.”

풀스케일 Analytics 도구(GA, Amplitude 등)를 붙이기보다는,우리가 이미 사용 중인 Sentry 위에 간단한 방문 지표만 얹어도 충분하지 않을까? 라는 판단을 했고, 다음 두 가지를 기준으로 info 레벨 이벤트를 직접 쌓는 방식을 택했다.

1. 페이지 방문(라우터 이동)
2. 모달 오픈

---

1. 페이지 방문 이벤트 로깅

페이지 방문은 Next.js의 라우터 이벤트를 활용해 감지했다. 핵심 아이디어는 간단하다.

• routeChangeComplete 이벤트가 발생할 때마다 Sentry에 level: 'info' 인 이벤트를 남긴다.
• 메시지에는 “페이지 방문: [라우트 패턴]” 을 기록하고,
• 태그에는 라우트 패턴(route) + 실제 path(path) 를 함께 남긴다.

 

// app.tsx (또는 _app.tsx)

useEffect(() => {
  const sendPageView = (url?: string) => {
    try {
      const routePattern =
        (router as any)?.router?.pathname ??
        (router as any)?.router?.route ??
        '';
      const path =
        typeof window !== 'undefined'
          ? (url ?? window.location.pathname + (window.location.search || ''))
          : '';

      Sentry.captureEvent({
        message: `페이지 방문: ${routePattern}`,
        level: 'info',
        tags: {
          route: routePattern || '(unknown)', // Next.js 라우트 패턴 (/projects/[id] 등)
          path,                               // 실제 path (/projects/123?tab=info 등)
        },
      });
    } catch (err) {
      Sentry.captureException(err);
    }
  };

  const handleRouteDone = (url: string) => sendPageView(url);

  router.events.on('routeChangeComplete', handleRouteDone);
  // 첫 로드
  sendPageView();

  return () => {
    router.events.off('routeChangeComplete', handleRouteDone);
  };
}, []);

여기서 route vs path 를 나눈 이유는 다음과 같다.

• route : /rulepacks/[id], /references/[refId]/detail 같은 패턴 단위 통계를 보기 위함
• path : /rulepacks/123?tab=settings 같이 실제 접근 URL을 보고 싶을 때 사용

이렇게 해두면 Sentry에서:

• message:"페이지 방문" 이라는 메시지를 기준으로 필터링
• route 태그 기준으로 그룹핑해서 “어떤 기능 단위 페이지가 많이 방문되었는지”를 빠르게 확인할 수 있다.

---

4-2. 모달 방문 이벤트 로깅 (Custom Hook)

페이지 방문은 라우터 이벤트로 감지하면 되지만, 모달은 URL이 변하지 않는 경우가 대부분이기 때문에 라우터로는 감지할 수 없다.

그래서 모달에 대해서는 다음 형태의 패턴을 만들었다.

“모달이 열릴 때(= isOpen이 true가 되는 시점에) 딱 한 번 Sentry info 이벤트를 남기는 훅”

그 결과물이 useTrackModalOpen 이다.

// hooks/useTrackModalOpen.ts
import { useEffect } from 'react';
import { useRouter } from 'next/router';
import * as Sentry from '@sentry/nextjs';

export interface TrackModalOpenOptions {
  message: string;
  route?: string;
  includePath?: boolean;
  tags?: Record<string, string | number | boolean | null | undefined>;
}

/**
 * 모달이 open 상태가 되는 시점에 Sentry 이벤트를 한 번 기록하는 훅.
 * 기본적으로 route(패턴) 태그를 남기고, 옵션에 따라 path 및 추가 태그도 기록한다.
 */
export function useTrackModalOpen(
  isOpen: boolean,
  { message, route, includePath = true, tags }: TrackModalOpenOptions,
): void {
  const router = useRouter();

  useEffect(() => {
    if (!isOpen) return;

    try {
      const routeTag =
        route ??
        (router as any)?.pathname ??
        (router as any)?.route ??
        '(unknown)';

      let pathTag = '';
      if (includePath && typeof window !== 'undefined') {
        const pathname = window.location.pathname;
        const search = window.location.search || '';
        pathTag = `${pathname}${search}`;
      }

      const finalTags: Record<string, string> = {
        route: String(routeTag),
      };
      if (includePath && pathTag) {
        finalTags.path = pathTag;
      }
      if (tags) {
        for (const [key, value] of Object.entries(tags)) {
          if (value !== undefined && value !== null) {
            finalTags[key] = String(value);
          }
        }
      }

      Sentry.captureEvent({
        message,
        level: 'info',
        tags: finalTags,
      });
    } catch (error) {
      Sentry.captureException(error);
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isOpen]);
}

 

 

사용자는 모달 컴포넌트에서 다음처럼 간단히 호출만 하면 된다.

import { useTrackModalOpen } from '@/hooks/useTrackModalOpen';

function RulepackDeleteModal({ isOpen }: { isOpen: boolean }) {
  useTrackModalOpen(isOpen, {
    message: '모달 방문: 룰팩 삭제',
    includePath: true,
    tags: { modal: 'rulepack_delete' },
  });

  // ... 나머지 모달 UI
}

 

결과

discover탭에서savedQuries에 쿼리를 커스텀하여 metrics 지표 생성하였다.

(message:"페이지 방문:*" OR message:"모달 방문:*") event.type:default(message:"페이지 방문:*" OR message:"모달 방문:*") event.type:default

 

metric 데이터 커스텀

 

 

 

 

먼저 sentry를 적용해보겠다고 나선 이후 구축부터 적용까지 내 손으로 일궜는데, 실제로 해당 데이터를 통해 원인을 빠르게 파악할 수 있어서 유용하게 쓰이고 있다. 구축도 어려웠지만 소스맵 연동할 때가 제일 힘들었는데 그래도 적용을 완료해서 잘 사용하고 있어서 매우 뿌듯한 경험이었다.