설정

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

init() vs initSDK()

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

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

SDKConfig 옵션

핵심

캡처 토글

시그널 토글

라이프사이클 & 진단

고급 / 확장

예시

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 },
  },
});

데이터베이스 쿼리 트레이싱

pg와 mysql2는 기본 자동 계측 대상이므로 쿼리 스팬은 별도 설정 없이 생성됩니다. 다만 그 스팬은 애플리케이션이 관측한 범위까지만 담습니다. 데이터베이스 내부의 실행계획까지 같은 트레이스로 이으려면 쿼리에 W3C traceparent를 실어 보내야 하며, 이를 담당하는 SQLCommenter는 기본값으로 비활성화되어 있습니다.

init({
  service: 'checkout-api',
  apiKey: process.env.SOPHONZ_API_KEY,
  instrumentations: {
    '@opentelemetry/instrumentation-pg': {
      addSqlCommenterCommentToQueries: true,
    },
  },
});

활성화하면 모든 문장 끝에 트레이스 컨텍스트가 주석으로 붙습니다.

SELECT id, email FROM users WHERE id = $1; /*traceparent='00-d4cda95b652f4a1592b449d5929fda1b-6e0c63257de34c92-01'*/

지원 여부는 계측마다 다릅니다.

데이터베이스가 이 주석을 읽어 서버 측 스팬을 생성하려면 PostgreSQL에 pg_tracing 확장이 필요합니다. 자체 운영 PostgreSQL을 참고하세요. 확장이 없는 환경에서도 주석은 데이터베이스 로그에 기록되므로, 이후 로그와 트레이스를 결합하는 근거가 됩니다.

환경 변수

Sophonz 전용

OpenTelemetry