콘텐츠로 이동
dev-docs

Next.js | Next.js용 Sentry

출처 URL: https://docs.sentry.io/platforms/javascript/guides/nextjs

Next.js | Next.js용 Sentry

섹션 제목: “Next.js | Next.js용 Sentry”

사전 요구 사항

섹션 제목: “사전 요구 사항”

필요한 항목:

설치

섹션 제목: “설치”

Sentry 마법사를 실행하면 Next.js 애플리케이션에 Sentry가 자동으로 구성됩니다:

Terminal window
npx @sentry/wizard@latest -i nextjs

마법사가 기능 선택을 요청합니다. 활성화할 기능을 선택하세요:

  • 오류 모니터링 [x]
  • 로그 [ ]
  • 세션 리플레이 [x]
  • 트레이싱

직접 설정하고 싶으신가요? 수동 설정 가이드를 확인하세요.

마법사가 생성한 항목

섹션 제목: “마법사가 생성한 항목”

마법사는 모든 Next.js 런타임 환경에 대해 Sentry를 구성하고, 설정을 테스트할 파일도 생성했습니다.

Next.js는 서로 다른 환경에서 코드를 실행합니다. 마법사는 각 환경별로 별도의 초기화 파일을 생성합니다:

  • 클라이언트 (instrumentation-client.ts) — 브라우저에서 실행
  • 서버 (sentry.server.config.ts) — Node.js에서 실행
  • 엣지 (sentry.edge.config.ts) — 엣지 런타임에서 실행

instrumentation-client.ts

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


Sentry.init({
  dsn: "___PUBLIC_DSN___",


  // 사용자에 대한 요청 헤더와 IP를 추가합니다
  sendDefaultPii: true,
  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  // ___PRODUCT_OPTION_START___ logs
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
});
프로덕션용 샘플링 비율 조정
섹션 제목: “프로덕션용 샘플링 비율 조정”

위 예시는 개발 환경에서 트레이스의 100%, 프로덕션 환경에서 10%를 샘플링합니다. 사용량 통계를 모니터링하고 트래픽 규모에 따라 tracesSampleRate를 조정하세요. 샘플링 구성에 대해 더 알아보세요.

instrumentation.ts 파일은 서버 및 엣지 구성을 Next.js에 등록합니다.

instrumentation.ts

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


export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}


export const onRequestError = Sentry.captureRequestError;

next.config.ts는 withSentryConfig로 감싸져 소스 맵 업로드, 터널링(광고 차단기 회피), 기타 빌드 시점 기능을 활성화합니다.

next.config.ts

import { withSentryConfig } from "@sentry/nextjs";


export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",


  // 읽기 쉬운 스택 트레이스를 위해 소스 맵을 업로드합니다
  authToken: process.env.SENTRY_AUTH_TOKEN,


  // Sentry 요청을 서버를 통해 전달합니다(광고 차단기 우회)
  tunnelRoute: "/monitoring",


  silent: !process.env.CI,
});

마법사는 App Router 애플리케이션에서 React 렌더링 오류를 캡처하기 위해 app/global-error.tsx를 생성합니다.

app/global-error.tsx

"use client";


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


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


  return (
    <html>
      <body>
        <h1>문제가 발생했습니다!</h1>
      </body>
    </html>
  );
}

마법사는 소스 맵 업로드용 auth token이 포함된 .env.sentry-build-plugin을 생성합니다. 이 파일은 자동으로 .gitignore에 추가됩니다.

CI/CD에서는 빌드 시스템에 SENTRY_AUTH_TOKEN 환경 변수를 설정하세요.

.env.sentry-build-plugin

Terminal window
SENTRY_AUTH_TOKEN=sntrys_eyJ...

마법사는 테스트 오류를 발생시키는 버튼이 있는 /sentry-example-page를 생성합니다. 이를 사용해 설정을 검증하세요.

Terminal window
app/
├── sentry-example-page/
│   └── page.tsx       # 오류 버튼이 있는 테스트 페이지
└── api/
    └── sentry-example-api/
        └── route.ts   # 테스트 API 라우트

설정 검증

섹션 제목: “설정 검증”
중요
섹션 제목: “중요”

브라우저 개발자 도구(예: 브라우저 콘솔) 내부에서 트리거된 오류는 샌드박싱되므로 Sentry 오류 모니터링을 트리거하지 않습니다.

예제 페이지는 한 번의 동작으로 활성화한 모든 기능을 테스트합니다:

  1. 개발 서버를 시작하세요:
Terminal window
npm run dev

  1. localhost:3000/sentry-example-page 방문

  2. “샘플 오류 발생시키기” 클릭

오류 — 이슈 열기

소스 코드를 가리키는 전체 스택 트레이스와 함께 “This is a test error”가 표시되어야 합니다.

트레이싱 — 트레이스 열기

페이지 로드 트레이스와 버튼 클릭 span이 표시되어야 합니다. 사용자 정의 span에 대해 더 알아보세요.

세션 리플레이 — 리플레이 열기

오류가 발생한 순간을 포함한 세션의 영상 같은 기록을 확인하세요. Session Replay 구성에 대해 더 알아보세요.

로그 — 로그 열기

애플리케이션의 구조화된 로그 항목을 확인하세요. 어디서든 로그를 보낼 수 있습니다:

Sentry.logger.info("사용자 동작", { userId: "123" });
Sentry.logger.warn("응답이 느립니다", { duration: 5000 });
Sentry.logger.error("작업이 실패했습니다", { reason: "timeout" });

Logs 구성에 대해 더 알아보세요.

SDK 설정 중 문제가 있나요?

다음 단계

섹션 제목: “다음 단계”

Next.js 애플리케이션에 Sentry를 성공적으로 통합했습니다! 다음 항목을 살펴보세요:

기타 JavaScript 프레임워크

섹션 제목: “기타 JavaScript 프레임워크”

주제

섹션 제목: “주제”