설치

@sophonz/nextjs 설치, instrumentation.ts에 register() 연결하기, App Router 루트 레이아웃에 SophonzProvider 마운트하기.

@sophonz/nextjs를 설치하고, instrumentation.ts에 register()를 연결한 뒤, 루트 레이아웃에 SophonzProvider를 마운트하세요.

요구 사항

  • Next.js >= 13.4.0, App Router
  • React >= 18

NOTE — Next.js 15 미만에서의 instrumentation.ts

instrumentation.ts는 Next.js 15부터 플래그 없이 안정화되었습니다. 이전 버전에서는 먼저 활성화해야 합니다.

// next.config.js
module.exports = {
  experimental: { instrumentationHook: true },
};

설치

bun add @sophonz/nextjs
# 또는
pnpm add @sophonz/nextjs
# 또는
npm install @sophonz/nextjs

서버: register() 연결하기

프로젝트 루트에 instrumentation.ts를 만듭니다.

// instrumentation.ts
export { register } from '@sophonz/nextjs/server';

Next는 서버 프로세스당 한 번, 어떤 요청도 처리되기 전에 register()를 호출합니다. 자동 계측이 의존하는 모듈 패치가 가능한 유일한 시점입니다.

환경 변수 대신 코드로 설정하려면 감싸서 내보내세요.

// instrumentation.ts
import { register as sophonz } from '@sophonz/nextjs/server';
 
export const register = () =>
  sophonz({
    appName: 'my-app',
    server: { advancedNetworkCapture: true },
  });

register()는 Edge 런타임에서 아무 동작도 하지 않습니다. process.env.NEXT_RUNTIME을 직접 비교하도록 작성되어 있어 번들러가 이 분기를 접고, Edge 번들에서 Node.js SDK 자체가 빠집니다.

클라이언트: SophonzProvider 마운트하기

모든 라우트가 커버되도록 루트 레이아웃에 한 번만 추가합니다.

// app/layout.tsx
import { SophonzProvider } from '@sophonz/nextjs/client';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <SophonzProvider>{children}</SophonzProvider>
      </body>
    </html>
  );
}

SophonzProvider는 Client Component이며, 주변 레이아웃은 그대로 Server Component로 남습니다. 마운트 시 한 번만 초기화하고 @sophonz/browser-sdk를 동적으로 import하므로 최초 렌더링을 막지 않습니다.

환경 변수

양쪽 모두 같은 변수를 읽습니다. .env에 한 번만 설정하세요.

NEXT_PUBLIC_SOPHONZ_COLLECTOR_URL=https://in.sophonz.ai
NEXT_PUBLIC_SOPHONZ_APP_NAME=my-app
NEXT_PUBLIC_SOPHONZ_APP_VERSION=1.0.0
NEXT_PUBLIC_SOPHONZ_APP_KEY=your-app-key
NEXT_PUBLIC_SOPHONZ_PROJECT=my-project
NEXT_PUBLIC_SOPHONZ_ENVIRONMENT=production

CAUTION — NEXT_PUBLIC_은 브라우저까지 전달됩니다

Next는 NEXT_PUBLIC_ 접두사가 붙은 값만 클라이언트 번들에 인라인하므로, appKey를 포함한 공유 필드는 모두 이 접두사를 사용합니다. appKey는 수집 키이지 액세스 토큰이 아니므로 브라우저로 보내도 안전합니다.

계측 대상 패키지를 external로 유지하기

OpenTelemetry는 Node의 require 훅으로 모듈을 패치합니다. 번들에 인라인된 모듈은 런타임에 require되지 않으므로 훅이 놓치고, 그 모듈이 감싸는 DB·HTTP 클라이언트의 스팬이 사라집니다.

// next.config.js
module.exports = {
  serverExternalPackages: ['@sophonz/nextjs', '@sophonz/node-sdk'],
};

NOTE — 이전 버전의 Next.js

serverExternalPackages는 Next.js 15에서 experimental을 벗어나 안정화되었습니다. 이전 버전에서는 experimental.serverComponentsExternalPackages를 대신 사용하세요.

다음 단계

  • 설정 — 전체 SophonzNextConfig 레퍼런스와 환경 변수.
  • Node.js SDK, Web SDK — 이 패키지가 내부에서 구성하는 두 SDK.