사내 보안 리소스 통합 플랫폼 구축기 : 4. sentry self-hosted (on-premise) 세팅 with next.js

1. Sentry란?

Sentry는 애플리케이션에서 발생하는 에러 및 예외를 실시간으로 수집하고 시각화하여 빠르게 문제를 파악하고 대응할 수 있게 돕는 오픈소스 기반의 오류 추적 시스템이다.

주로 웹, 모바일, 데스크탑 등 다양한 플랫폼에서 발생하는 런타임 오류나 성능 저하 이슈를 추적하는 데 활용된다.

“Application Monitoring and Error Tracking that helps developers see what actually matters, solve quicker, and learn continuously in production.”

2. Sentry로 할 수 있는 것들

• ✅ 에러 추적
• 에러 발생 시 스택 트레이스를 포함한 상세 로그를 수집해 어디서 문제가 발생했는지 시각적으로 파악할 수 있음
• ✅ 이슈 자동 분류 및 그룹화
• 동일한 종류의 에러를 하나의 이슈로 묶어 관리할 수 있어 이슈 정리가 수월함
• ✅ 알림 설정
• 슬랙, 이메일, 웹훅 등 다양한 방식으로 알림을 받을 수 있음 → 나중에 디스코드 알람 연동
• ✅ 릴리즈 트래킹
• 어떤 배포 버전에서 어떤 오류가 발생했는지 추적 가능
• ✅ 성능 모니터링
• API 응답 시간, 트랜잭션 병목 현상 등을 추적하여 성능 개선에 기여 가능

---

3. Sentry SaaS vs On-Premise

항목	SaaS (sentry.io)	On-Premise
호스팅	Sentry 클라우드에서 운영	사내 인프라에서 직접 운영
설치/유지보수	없음 (자동 제공)	직접 설치 및 관리 필요
보안/데이터 통제	외부 저장	내부망 유지 가능 (보안 강화)
확장성	Sentry가 관리	자체적으로 구성 필요
요금	사용량 기반 유료	무료 (오픈소스) or 자체 인프라 비용

보안이 중요한 기업 환경에서는 On-Premise가 선호됨

 

---

4. 왜 우리는 Sentry를 도입했나?

우리 팀은 사용자 환경에서 발생하는 프론트엔드 오류를 사전에 인지하고 신속히 대응하기 위한 방안으로 Sentry를 도입했다.

특히, 사내 서비스가 올라간 환경이 외부 클라우드 서비스 사용이 제한된 폐쇄망 환경이었기 때문에, Sentry SaaS가 아닌 On-Premise 버전을 선택하여 사내 인프라에 직접 구축했다.

또한, 전담 QA 프로세스를 별도로 운영하지 않고 있는 상황에서, 서비스 관련 오류를 사람이 수동으로 찾는 방식에는 한계가 있었고, 에러를 자동으로 수집하고 분류해주는 시스템이 필요하다고 판단했다.

🧩 도입 전 문제점

• 콘솔 로그가 수집되지 않아 사용자 이슈 파악에 한계
• 별도의 QA가 따로 있지 않아 이슈가 뒤늦게 발견
• 재현 불가능한 버그 발생 시 정확한 원인 파악이 어려움

✅ 도입 후 기대 효과

• 프론트엔드 오류의 실시간 감지 및 Discord 알림 자동화
• 스택 트레이스를 통한 빠르고 정확한 오류 위치 분석
• 어떤 코드 릴리즈 버전에서 문제가 발생했는지 버전별 추적 가능

Sentry 도입을 통해, 서비스 운영 안정성을 확보하고 사용자 경험을 개선할 수 있는 기반을 마련할 수 있었다.

 

5. 설치 및 연동 방법

🐶
on-premise 환경의 sentry self-hosted 방법은 docker compose를 활용한다.
따라서 사전에 docker 환경이 세팅되어야 한다.
나의 경우 이미 docker가 설치되어 있어 docker 환경 세팅에 대해서는 따로 다루지 않는다.

 

✅ on-premise sentry self-host 서버 설치

1. sentry self-host 을 클론 받아온다.

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/getsentry/self-hosted/releases/latest)
VERSION=${VERSION##*/}

sentry self- hosted docs에서는 version을 최신으로 땡겨오는 script가 다음과 같았으나 오류가 발생하여 특정 버전을 지정하였다.

(아래 명령어 참고)

VERSION="25.5.1"
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git checkout ${VERSION}

 

2.  클론 받아온 브랜치 내부의 install관련 script를 실행한다

sudo ./install.sh

 

중간에 나오는 프롬프트
1. 에러 내용 sentry에 공유 여부 (y/n 마음대로)
2. admin 계정 만들지 여부 - 어차피 로그인 할 계정이 필요해서 yes 후, 사용할 이메일 계정과 패스워드 입력

 

3. 완료 후 docker compose를 실행한다.

docker compose up -d

 

4. localhost:9000 또는 서버주소:9000 로 접속한다.

• sentry는 9000 port가 default

self-hosted 설치 프롬프트에서 등록한 계정으로 로그인 가능하다.

 

✅ 프론트 연동하기

1. sentry에 관리자 계정으로 로그인 후 프로젝트를 추가한다.

1-1. 프론트 프로젝트는 next.js 로 next.js를 선택 한다.

1-2. 그 외 프로젝트 이름과 알람 주기를 선택한다.

 

2. sentry 프로젝트와 프론트를 연동한다.

2-1. 프론트 프로젝트에 다음 의존성을 추가한다.

yarn add @sentry/nextjs

2-2. sentry wizard를 다음 명령어로 실행한다.

 

npx @sentry/wizard@latest -i nextjs --org sentry --project [프로젝트 명]

 

Sentry Wizard Prompt 정리

질문 응답	선택 내용	비고
📦 You have uncommitted or untracked files in your repo: (계속할까요?)	✅ Yes	package.json 등 수정 예정이므로 확인
☁️ Are you using Sentry SaaS or self-hosted Sentry?	✅ Self-hosted/on-premise/single-tenant	온프레미스 환경 선택
🌐 Please enter the URL of your self-hosted Sentry instance.	✅ http://서버주소:9000/	사내 서버 URL 입력
🔑 The @sentry/nextjs package is already installed. Do you want to update it to the latest version?	✅ Yes	SDK 최신 버전으로 업데이트
🚫 Do you want to route Sentry requests through your Next.js server to avoid ad blockers?	❌ No	브라우저에서 직접 전송 유지
🚀 Do you want to enable Tracing to track the performance of your application?	✅ Yes	퍼포먼스 트레이싱 활성화
🎥 Do you want to enable Session Replay...?	✅ Yes	사용자 행동 리플레이 기능 활성화
📄 Do you want to create an example page ("/sentry-example-page")...?	✅ Yes	테스트용 샘플 페이지 생성
🛠️ Are you using a CI/CD tool to build and deploy your application?	✅ Yes	CI 환경 사용 여부
🔐 Add the Sentry authentication token as an environment variable...	⚠️ 나중에 추가 (I'll do it later...)	.env.sentry-build-plugin 파일에 토큰 저장됨
🎨 Looks like you have Prettier... Do you want to run it on your files?	✅ Yes	Prettier로 코드 자동 정렬

---

 

📝 자동으로 생성된 파일들

파일	설명
sentry.server.config.ts	서버 사이드용 Sentry 설정
sentry.edge.config.ts	엣지 런타임용 Sentry 설정
instrumentation.ts / instrumentation-client.ts	성능 추적 및 리플레이 관련 코드
pages/_error.jsx	에러 바운더리 페이지 커스터마이징
pages/sentry-example-page.js	테스트용 샘플 페이지
pages/api/sentry-example-api.js	API 테스트용 샘플
.env.sentry-build-plugin	로컬 테스트용 인증 토큰 포함
.gitignore	.env.sentry-build-plugin 자동 추가됨

 

 

🔥 trouble shooting

💥 sentry 관리자 계정으로 로그인 시 CSRF 오류가 나는 현상

 

원인

• system.url-prefix 설정 누락 또는 오류
• Sentry는 CSRF 토큰을 검증할 때 요청 도메인과 설정된 system.url-prefix를 비교합니다. 만약 이 값이 잘못되어 있으면 CSRF 오류가 발생할 수 있습니다.

해결 방법

1. self-hosted/sentry/config.yml 파일을 열고, 아래와 같이 system.url-prefix를 정확한 도메인으로 설정

# self-hosted/sentry/config.yml 

# The URL prefix in which Sentry is accessible
system.url-prefix: [sentry 서버주소]

 

2. docker compose 종료 후 재실행

docker compose down
docker compose up -d

 

💥 wizard가 실행되지 않는 현상

wizard가 실행되다 멈추고 error log파일이 생성되었다.

// wizard-error-log 파일 일부
warning "@sentry/nextjs > @sentry/opentelemetry@9.29.0" has unmet peer dependency "@opentelemetry/context-async-hooks@^1.30.1 || ^2.0.0".
warning "@sentry/nextjs > @sentry/opentelemetry@9.29.0" has unmet peer dependency "@opentelemetry/core@^1.30.1 || ^2.0.0".
warning "@sentry/nextjs > @sentry/opentelemetry@9.29.0" has unmet peer dependency "@opentelemetry/instrumentation@^0.57.1 || ^0.200.0".
warning "@sentry/nextjs > @sentry/opentelemetry@9.29.0" has unmet peer dependency "@opentelemetry/sdk-trace-base@^1.30.1 || ^2.0.0".
warning "@sentry/nextjs > @sentry/webpack-plugin@3.5.0" has unmet peer dependency "webpack@>=4.40.0".
error An unexpected error occurred: "EPERM: operation not permitted, copyfile 'C:\\Users\\luminous\\AppData\\Local\\Yarn\\Cache\\v6\\npm-@types-estree-1.0.6-628effeeae2064a1b4e79f78e81d87b7e5fc7b50-integrity\\node_modules\\@types\\estree\\flow.d.ts' -> 'D:\\project\\node_modules\\rollup\\node_modules\\@types\\estree\\flow.d.ts'".

 

원인

프로젝트 추가 시 안내되는 문구에서는 wizard를 실행하는 명령어를 사용하도록 안내되어 있었다.

하지만 오류가 발생했고, 공식 문서를 확인해보니 sentry 관련 의존성을 안내 없어도 따로 설치해야 했다.

 

 

해결 방법

yarn add @sentry/nextjs

해당 의존성을 설치 후 wizard 실행 시 정상 실행된다.

 

 

Reference

---

https://infiduk.github.io/2024/10/30/sentry.html

https://infiduk.github.io/2024/10/30/sentry.html

https://develop.sentry.dev/self-hosted/#getting-started

https://sig03.medium.com/sentry-self-hosted-설치-방법-d6f3b57b71cf

https://devkingstar.tistory.com/183

https://pungwa.tistory.com/173

https://engineering.linecorp.com/ko/blog/log-collection-system-sentry-on-premise

https://techblog.woowahan.com/21604/

https://tech.codedream.co.kr/25

https://github.com/getsentry/self-hosted

https://velog.io/@ljo094822/nextjs-13-sentry-적용기