Sentry 런타임 에러 모니터링 실전 2026 | Next.js 설치·소스맵·알림

센트리 Next.js 위저드 실행
# 프로젝트 루트에서
npx @sentry/wizard@latest -i nextjs

# 위저드가 묻는 항목 예시
# - Login / org / project 선택
# - Error Monitoring: Yes
# - Session Replay: 팀 정책에 맞게 (PII 주의)
# - Tracing(성능): 초기엔 sample rate 낮게
# - CI 업로드(소스맵): 가능하면 Yes

환경 변수 예시 (.env.local)
# 공개 DSN (클라이언트에도 노출 가능)
NEXT_PUBLIC_SENTRY_DSN=https://xxxx@o0.ingest.sentry.io/0

# 소스맵 업로드용 (서버/CI 전용, 커밋 금지)
SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug

# 릴리스 이름 (선택, 빌드 파이프라인에서 주입 권장)
SENTRY_RELEASE=web@1.4.2+abc1234

sentry.client.config.ts 최소 예
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  // 개발 중 전송을 끄려면 true
  enabled: process.env.NODE_ENV === 'production',
  tracesSampleRate: 0.1,
  // 세션 리플레이는 동의·마스킹 정책 확정 후
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0.2,
  beforeSend(event) {
    // 이메일·토큰 등 민감 필드 제거 훅
    if (event.request?.headers) {
      delete event.request.headers['authorization']
    }
    return event
  },
})

sentry.server.config.ts 최소 예
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  enabled: process.env.NODE_ENV === 'production',
  tracesSampleRate: 0.1,
  // 서버에서 잡힌 예외에 공통 태그
  initialScope: {
    tags: { runtime: 'nodejs' },
  },
})

클라이언트 테스트 버튼 (App Router)
'use client'

import * as Sentry from '@sentry/nextjs'

export function SentryTestButton() {
  return (
    <button
      type="button"
      onClick={() => {
        Sentry.captureException(new Error('sentry client test error'))
        // 또는 throw new Error('unhandled client test')
      }}
    >
      센트리 클라이언트 테스트
    </button>
  )
}

서버 라우트 테스트 (app/api/sentry-test/route.ts)
import * as Sentry from '@sentry/nextjs'
import { NextResponse } from 'next/server'

export async function GET() {
  try {
    throw new Error('sentry server test error')
  } catch (err) {
    Sentry.captureException(err)
    await Sentry.flush(2000)
    return NextResponse.json({ ok: false, captured: true }, { status: 500 })
  }
}

로그인 후 setUser / setTag 예
import * as Sentry from '@sentry/nextjs'

export function identifySentryUser(user: {
  id: string
  email?: string
  plan?: string
}) {
  Sentry.setUser({
    id: user.id,
    // 이메일은 개인정보 정책에 따라 해시만 권장
    email: user.email,
  })
  if (user.plan) {
    Sentry.setTag('plan', user.plan)
  }
  Sentry.setContext('app', {
    locale: 'ko-KR',
    surface: 'web',
  })
}

export function clearSentryUser() {
  Sentry.setUser(null)
}

브레드크럼으로 직전 행동 남기기
import * as Sentry from '@sentry/nextjs'

export async function onCheckoutClick(cartId: string) {
  Sentry.addBreadcrumb({
    category: 'checkout',
    message: 'checkout button clicked',
    level: 'info',
    data: { cartId },
  })

  try {
    // await startCheckout(cartId)
  } catch (err) {
    Sentry.captureException(err, {
      tags: { flow: 'checkout' },
      extra: { cartId },
    })
    throw err
  }
}

withSentryConfig 래핑 스케치 (next.config)
const { withSentryConfig } = require('@sentry/nextjs')

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 기존 설정...
}

module.exports = withSentryConfig(nextConfig, {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,
  silent: !process.env.CI,
  widenClientFileUpload: true,
  // 소스맵을 클라이언트에 공개하지 않으려면 hideSourceMaps 등 옵션 확인
})

GitHub Actions에서 릴리스 이름 주입 예
# .github/workflows/deploy.yml 일부
env:
  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  SENTRY_ORG: your-org
  SENTRY_PROJECT: your-project
  SENTRY_RELEASE: web@${{ github.sha }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
        env:
          NEXT_PUBLIC_SENTRY_DSN: ${{ secrets.NEXT_PUBLIC_SENTRY_DSN }}
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ env.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ env.SENTRY_PROJECT }}
          SENTRY_RELEASE: ${{ env.SENTRY_RELEASE }}