설치

@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 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.