설정

Sophonz Node.js SDK 설정 레퍼런스 — init()/initSDK()의 SDKConfig 옵션과 SOPHONZ_* / OTEL_* 환경 변수.

SDK는 init() / initSDK()에 전달하는 SDKConfig 옵션 또는 환경 변수로 설정합니다. 옵션이 항상 환경 변수보다 우선하며, 환경 변수는 폴백입니다(그리고 프리로드 바이너리를 설정하는 유일한 방법입니다).

init() vs initSDK()

import { init, initSDK } from '@sophonz/node-sdk';

init(config?) — 권장 진입점. Sophonz 기본값(consoleCapture: true, experimentalExceptionCapture: true, sentryIntegrationEnabled: true, programmaticImports: true)을 적용하고 그 위에 사용자 설정을 병합합니다.
initSDK(config) — 저수준. 아래 옵션별 기본값만 적용하며 추가적인 동작은 켜지 않습니다. 완전한 제어가 필요할 때 사용하세요.

NOTE — programmaticImports

init()은 programmaticImports를 켜서 sdk.start() 이후 계측을 재패치합니다. 모듈이 이미 import된 상태(번들러나 TypeScript 트랜스파일에서 흔함)에서도 자동 계측이 동작하게 해 줍니다. initSDK()는 직접 설정하지 않는 한 꺼져 있습니다.

SDKConfig 옵션

핵심

옵션	타입	기본값	설명
`service`	`string`	`OTEL_SERVICE_NAME` 또는 자동 감지	모든 텔레메트리에 보고되는 서비스 이름.
`apiKey`	`string`	`SOPHONZ_API_KEY`	컬렉터에 `Authorization` 헤더로 전송되는 API 키.

캡처 토글

옵션	타입	기본값	설명
`consoleCapture`	`boolean`	`true`	`console.*`를 계측해 로그로 전달. `OTEL_LOG_LEVEL=debug`이면 자동 비활성화.
`experimentalExceptionCapture`	`boolean`	`false`*	처리되지 않은 예외와 reject 캡처.
`sentryIntegrationEnabled`	`boolean`	`false`*	Sentry SDK 통합 활성화.
`advancedNetworkCapture`	`boolean`	`false`	HTTP 요청/응답 헤더 캡처(`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_*`로 구성).

NOTE — * init()과 initSDK()의 기본값 차이

experimentalExceptionCapture와 sentryIntegrationEnabled는 initSDK()에서 false가 기본이지만 init()은 이를 켭니다. 표의 값은 initSDK() 기준 기본값입니다.

시그널 토글

옵션	타입	기본값	설명
`disableTracing`	`boolean`	`false`	트레이스 전송 비활성화.
`disableLogs`	`boolean`	`false`	로그 전송 비활성화.
`disableMetrics`	`boolean`	`false`	메트릭 전송 비활성화.
`detectResources`	`boolean`	`true`	리소스 속성(호스트, 프로세스, 클라우드 등) 자동 감지.

라이프사이클 & 진단

옵션	타입	기본값	설명
`stopOnTerminationSignals`	`boolean`	`true`	`SIGTERM` / `SIGINT` 시 플러시 후 종료. 직접 종료를 관리하려면 `false`.
`disableStartupLogs`	`boolean`	`false`	시작 스피너와 대시보드 링크 숨김.
`enableInternalProfiling`	`boolean`	`false`	각 계측의 패치 소요 시간 로깅.

고급 / 확장

옵션	타입	기본값	설명
`instrumentations`	`InstrumentationConfigMap`	`{}`	특정 자동 계측을 재정의하거나 비활성화.
`additionalInstrumentations`	`InstrumentationBase[]`	`[]`	사용자 정의 계측 등록.
`metricReader`	`MetricReader`	Sophonz 기본값	커스텀 메트릭 리더 지정.
`programmaticImports`	`boolean`	`false` (`init()`에서는 `true`)	시작 후 계측을 재패치해 이미 import된 모듈도 계측.

예시

import { initSDK } from '@sophonz/node-sdk';
 
initSDK({
  service: 'checkout-api',
  apiKey: process.env.SOPHONZ_API_KEY,
  consoleCapture: true,
  experimentalExceptionCapture: true,
  advancedNetworkCapture: true,
  disableMetrics: false,
  instrumentations: {
    // 노이즈가 많은 자동 계측 비활성화
    '@opentelemetry/instrumentation-fs': { enabled: false },
  },
});

환경 변수

Sophonz 전용

변수	기본값	설명
`SOPHONZ_API_KEY`	—	컬렉터용 API 키.
`SOPHONZ_NODE_CONSOLE_CAPTURE`	`true`	콘솔 캡처 활성화.
`SOPHONZ_NODE_ADVANCED_NETWORK_CAPTURE`	`false`	HTTP 헤더 캡처.
`SOPHONZ_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE`	`false`	처리되지 않은 예외 캡처.
`SOPHONZ_NODE_SENTRY_INTEGRATION_ENABLED`	`false`	Sentry 통합 활성화.
`SOPHONZ_NODE_STOP_ON_TERMINATION_SIGNALS`	`true`	`SIGTERM` / `SIGINT` 시 플러시.
`SOPHONZ_NODE_BETA_MODE`	`false`	베타 기능 활성화(전역 컨텍스트 전파, 커스텀 로그 메타데이터).
`SOPHONZ_NODE_ENABLE_INTERNAL_PROFILING`	`false`	계측 패치 시간 프로파일링.
`SOPHONZ_STARTUP_LOGS`	`true`	시작 배너와 대시보드 링크 표시.

OpenTelemetry

변수	기본값	설명
`OTEL_SERVICE_NAME`	자동 감지	서비스 이름.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`https://in-otel.sophonz.com`	OTLP 기본 엔드포인트(traces/logs/metrics 경로가 여기서 파생).
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`https://in-otel.sophonz.com/v1/traces`	트레이스 전송 엔드포인트.
`OTEL_EXPORTER_OTLP_HEADERS`	—	추가 OTLP 헤더(API 키가 `Authorization`으로 덧붙음).
`OTEL_TRACES_SAMPLER`	`parentbased_always_on`	트레이스 샘플러.
`OTEL_TRACES_SAMPLER_ARG`	`1`	샘플러 인자.
`OTEL_LOG_LEVEL`	—	SDK 진단 로그 레벨(`debug`이면 콘솔 캡처 비활성화).
`OTEL_LOGS_EXPORTER` / `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER`	—	`none`으로 설정하면 해당 시그널 비활성화.

TIP — 우선순위

disableLogs / disableTracing / disableMetrics 옵션이나 대응하는 OTEL_*_EXPORTER=none 모두 시그널을 끕니다. 둘 다 존재하면 명시적 SDKConfig 옵션이 우선합니다.