설정

@sophonz/nextjs 설정 전체 레퍼런스 — 공유 SophonzNextConfig 옵션, 환경 변수, 패키지가 지정하는 기본값, 하위 브라우저·Node SDK 옵션에 접근하는 방법.

앱의 양쪽은 resolveConfig()가 해석하는 하나의 SophonzNextConfig를 공유합니다. 서버에서는 register()에, 클라이언트에서는 <SophonzProvider>에 전달하세요 — 아무것도 지정하지 않으면 양쪽 모두 같은 NEXT_PUBLIC_SOPHONZ_* 환경 변수를 읽습니다.

전달한 설정이 우선합니다

import { resolveConfig } from '@sophonz/nextjs';

resolveConfig(input?)은 명시적으로 전달한 설정 객체를 환경 변수 위에 병합합니다. 전달한 필드는 그대로 우선하고, 생략한 필드는 대응하는 NEXT_PUBLIC_SOPHONZ_* 변수로 대체됩니다. register()와 SophonzProvider 모두 내부에서 이 함수를 호출하므로, 환경 변수만 설정하거나 양쪽에 같은 객체를 전달하면 두 쪽이 항상 일치합니다.

SophonzNextConfig

옵션	타입	환경 변수	설명
`collectorUrl`	`string`	`NEXT_PUBLIC_SOPHONZ_COLLECTOR_URL`	OTLP 콜렉터 base URL.
`appName`	`string`	`NEXT_PUBLIC_SOPHONZ_APP_NAME`	양쪽 모두에서 `service.name`으로 전송.
`appVersion`	`string`	`NEXT_PUBLIC_SOPHONZ_APP_VERSION`	`service.version`으로 전송.
`appKey`	`string`	`NEXT_PUBLIC_SOPHONZ_APP_KEY`	Sophonz 수집 키. `service.key`로 전송. 의도적으로 브라우저까지 전달됩니다 — 수집 키이지 액세스 토큰이 아닙니다.
`project`	`string` (선택)	`NEXT_PUBLIC_SOPHONZ_PROJECT`	`service.namespace`로 전송.
`deploymentEnvironment`	`string` (선택)	`NEXT_PUBLIC_SOPHONZ_ENVIRONMENT`	예: `production`.
`tracePropagationTargets`	`(string \| RegExp)[]` (선택)	—	브라우저가 `traceparent`를 붙일 origin. 지정하지 않으면 동일 origin만.
`debug`	`boolean` (선택)	`NEXT_PUBLIC_SOPHONZ_DEBUG`	양쪽 모두 상세 로그.
`browser`	`Record<string, unknown>` (선택)	—	`@sophonz/browser-sdk`의 `init()`으로 그대로 전달.
`server`	`Record<string, unknown>` (선택)	—	`@sophonz/node-sdk`의 `initSDK()`으로 그대로 전달.

collectorUrl, appName, appVersion, appKey는 필수입니다. 하나라도 빠지면 register()와 SophonzProvider 모두 경고를 남기고 초기화를 건너뜁니다 — 아래 무엇이 빠졌는지 확인하기를 참고하세요.

NOTE — debug 값 해석 방식

NEXT_PUBLIC_SOPHONZ_DEBUG는 "false"와 "0"을 제외한 모든 값을 true로 읽습니다 — false로 의도한 다른 문자열도 마찬가지입니다. "no" 같은 값 대신 아예 설정하지 않는 편이 안전합니다.

이 패키지가 지정하는 기본값

아래 기본값은 server / browser로 전달한 값 위에 적용됩니다 — 하위 SDK 자체 기본값과 겹치는 부분은 여러분이 전달한 값이 우선합니다.

tracePropagationTargets — 직접 지정하지 않으면 현재 origin만. 함께 계측하는 별도 API가 있다면 그 origin을 추가하고, 해당 origin의 CORS 설정에서 traceparent 헤더를 허용해야 합니다.
서버 betaMode: true — @sophonz/node-sdk의 setTraceAttributes()가 동작하는 데 필요합니다.
서버 disableStartupLogs: true — Node SDK의 시작 스피너를 끕니다. 서버 로그나 서버리스 로그 스트림에서는 노이즈일 뿐입니다.
브라우저 disableIntercom: true — 켜져 있지 않으면 브라우저 SDK가 전역 Intercom을 폴링하다가, 앱이 Intercom을 쓰지 않을 때 에러를 남깁니다. browser: { disableIntercom: false }로 다시 켤 수 있습니다.

하위 SDK 옵션에 접근하기

@sophonz/browser-sdk나 @sophonz/node-sdk가 지원하는 옵션은 browser / server를 통해 그대로 접근할 수 있습니다.

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

// app/layout.tsx
<SophonzProvider
  appName="my-app"
  tracePropagationTargets={[/^https:\/\/api\.example\.com/]}
  browser={{ disableReplay: false }}
/>

각 하위 SDK가 지원하는 전체 옵션 목록은 Node.js SDK 설정과 Web SDK 설정 레퍼런스를 참고하세요.

무엇이 빠졌는지 확인하기

import { resolveConfig, missingFields } from '@sophonz/nextjs';
 
const config = resolveConfig({ appName: 'my-app' });
missingFields(config); // 예: ['collectorUrl', 'appVersion', 'appKey']

missingFields()는 collectorUrl, appName, appVersion, appKey 중 아직 비어 있는 필드를 알려줍니다 — register()와 SophonzProvider가 시작 전에 수행하는 검사와 동일합니다.

register()의 반환값

import { register } from '@sophonz/nextjs/server';
 
const result = await register();
// { started: boolean, reason?: 'edge-runtime' | 'already-started' | 'incomplete-config', missing?: string[] }

started가 false인 이유는 reason으로 알 수 있습니다. Edge 런타임에서 호출됐거나, 이 프로세스에서 서버 SDK가 이미 시작됐거나, 필수 설정이 빠져 있는 경우(missing에 필드 이름이 나열됨)입니다.

요청 단위 속성 설정하기

Next.js에는 미들웨어 체인이 없어 Node SDK의 Express/Koa/Fastify 헬퍼를 사용할 수 없습니다. 대신 Route Handler 안에서 @sophonz/node-sdk의 setTraceAttributes()를 호출하세요.

import { setTraceAttributes } from '@sophonz/node-sdk';
 
export async function GET() {
  setTraceAttributes({ 'user.id': userId });
}

이 호출이 활성 스팬에 실제로 반영되는 것은 위 이 패키지가 지정하는 기본값에서 설명한 대로 server.betaMode가 기본으로 켜져 있기 때문입니다.