Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII
무슨 일이 일어나야 하는가
서버 구성 요소, 경로 처리기, 서버 작업 또는 브라우저의 오류는 읽을 수 있는 스택(축소된 번들이 아닌 파일 이름 및 소스 라인)과 함께 릴리스 표시가 있고 이벤트 시 개인 사용자 데이터 없이 Sentry로 이동합니다.
설치
npx @sentry/wizard@latest -i nextjs
마법사는 파일을 생성하고 next.config를 편집합니다. 그가 무엇을 했는지 파악한 다음 그들을 지지하세요.
instrumentation-client.ts(이전 버전의 SDK -sentry.client.config.ts) - 브라우저에서 초기화됩니다.sentry.server.config.ts및sentry.edge.config.ts- Node.js 및 Edge 런타임용.instrumentation.ts는 서버가 시작될 때 Next.js가 호출하는 진입점입니다.app/global-error.tsx— 루트 레이아웃에 대한 오류 제한입니다.
// 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;onRequestError는 경로 처리기 및 서버 작업에서 렌더링 오류가 발생할 때 호출되는 Next.js 15 후크입니다. 이 줄이 없으면 서버 오류가 Sentry에 도달하지 못하는 경우가 많습니다. Next.js는 오류 자체를 가로채서 사용자에게 오류 페이지를 표시합니다.
PII가 없는 서버 구성
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.APP_ENV ?? "production",
release: process.env.SENTRY_RELEASE,
sendDefaultPii: false,
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request) {
delete event.request.cookies;
delete event.request.data;
if (event.request.headers) {
delete event.request.headers.authorization;
delete event.request.headers.cookie;
}
}
return event;
},
});sendDefaultPii: false(기본값이지만 명시적인 것이 더 좋음) - SDK는 IP 주소, 쿠키 및 사용자 데이터 헤더를 첨부하지 않습니다.beforeSend- 마지막 줄: 통합이나 사용자 고유의 컨텍스트를 통해 얻을 수 있는 내용을 제거합니다. 요청 본문(request.data)은 특히 위험합니다. 여기에는 로그인 양식 및 결제 데이터의 비밀번호가 포함되어 있습니다.- 식별자:
Sentry.setUser({ id: user.id })로만 사용자를 지정합니다. 오류 이벤트의 이메일과 이름은 디버깅에 필요하지 않지만 제3자에 의해 저장됩니다. tracesSampleRate: 0.1- 성능 추적 요청의 10%입니다. 프로덕션에서 값이 1.0이면 할당량이 빠르게 소진됩니다.
오류 텍스트도 확인하세요. `throw new Error(${email} 사용자를 찾을 수 없습니다.) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii`는 이를 중지하지 않습니다.
클라이언트 및 세션 재생
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0.2,
integrations: [Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })],
});재생은 페이지의 DOM을 작성합니다. maskAllText 및 blockAllMedia는 기본적으로 활성화되어 있습니다. 페이지에 개인 정보가 포함되어 있지 않은지 확인하지 않고 비활성화하지 마십시오. 실패한 세션만 기록(replaysOnErrorSampleRate)하면 사용자를 지속적으로 모니터링하지 않고도 디버깅을 위한 컨텍스트를 제공할 수 있습니다.
브라우저의 DSN은 본질적으로 공개되어 이벤트 전송만 허용합니다. 다른 사람의 사이트가 귀하의 프로젝트를 방해하지 않도록 Sentry 프로젝트 설정(허용 도메인)에서 허용 도메인을 제한하세요.
소스 맵
// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = { /* ... */ };
export default withSentryConfig(nextConfig, {
org: "my-org",
project: "web",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: !process.env.CI,
widenClientFileUpload: true,
sourcemaps: { deleteSourcemapsAfterUpload: true },
});next build 동안 플러그인은 소스 맵을 Sentry에 로드합니다. deleteSourcemapsAfterUpload는 소스 코드가 사이트의 모든 사람과 공유되지 않도록 업로드 후 빌드에서 .map 파일을 제거합니다. 배포 후 확인: /_next/static/chunks/에서 .js.map에 대한 요청은 404를 반환해야 합니다.
SENTRY_AUTH_TOKEN는 프로젝트에 대한 쓰기 권한이 있는 비밀입니다. 이는 런타임이 아닌 빌드 단계의 CI에만 필요하며 NEXT_PUBLIC_ 접두사가 있는 변수에는 필요하지 않습니다.
진단
- 스택이 축소되었습니다. 소스 맵이 로드되지 않았거나 이벤트 릴리스가 다운로드 릴리스와 일치하지 않습니다.
sentry-cli sourcemaps explain <event_id>명령은 특정 이벤트가 기호화되지 않은 이유를 설명합니다. - 서버 오류가 발생하지 않습니다.
instrumentation.ts에onRequestError가 없거나, 파일이 프로젝트 루트에 없습니다(src/가 있는 경우 -src/내부). - 일부 사용자에게는 브라우저 오류가 발생하지 않습니다. 광고 차단기는 Sentry에 대한 요청을 차단합니다.
withSentryConfig의tunnelRoute: "/monitoring"옵션은 도메인을 통해 이벤트를 프록시합니다. 사이트에 엄격한 CSP가 있는 경우connect-src에 수신 도메인을 추가하세요. - 아무것도 도착하지 않습니다.
Sentry.init에서debug: true를 임시로 활성화하고 서버 로그와 브라우저 콘솔을 확인합니다.
노이즈 및 할당량
모든 실수가 그만한 가치가 있는 것은 아닙니다. 취소된 요청, 브라우저 확장 오류, 봇의 404 등 예상되는 항목을 필터링합니다. 알려진 메시지에는 ignoreErrors를 사용하고 확장 스크립트에는 denyUrls를 사용하세요. 매일 수천 개의 동일하고 중요하지 않은 오류가 발생하는 프로젝트는 팀에게 Sentry를 전혀 보지 말라고 가르쳤습니다.
Sentry가 중복되는 경우
소규모 내부 서비스의 경우 error 수준의 구조화된 로그와 해당 개수에 대한 경고로 충분할 수 있습니다. Sentry는 클라이언트 측 JavaScript가 있고 사용자가 많으며 오류를 그룹화하고 어떤 릴리스에서 오류가 발생했는지 확인해야 할 때 효과가 있습니다.