설치

Sophonz Node.js SDK 설치 및 초기화 — init()을 사용한 프로그래밍 방식 또는 opentelemetry-instrument 프리로드 바이너리 방식.

설치

bun add @sophonz/node-sdk
# 또는
pnpm add @sophonz/node-sdk
# 또는
npm install @sophonz/node-sdk

프로그래밍 방식 초기화

init()은 가능한 한 빨리 — 진입 파일의 첫 import로 — 호출해 프레임워크와 데이터베이스 클라이언트가 로드되기 전에 실행되도록 하세요.

// instrument.ts (가장 먼저 import)
import { init } from '@sophonz/node-sdk';
 
init({
  service: 'my-app',
  apiKey: process.env.SOPHONZ_API_KEY,
});

// index.ts
import './instrument';
import express from 'express';
 
const app = express();
// ...

init()은 기본 SDK 위에 Sophonz 권장 기본값(콘솔 캡처, 실험적 예외 캡처, Sentry 통합, 계측 재패치)을 적용합니다. 모든 옵션을 직접 제어하려면 initSDK()를 사용하세요. 설정을 참고하세요.

정상 종료

기본적으로 SDK는 SIGTERM / SIGINT 시 텔레메트리를 플러시합니다. stopOnTerminationSignals: false로 비활성화했다면 종료 전에 직접 플러시하세요.

import { shutdown } from '@sophonz/node-sdk';
 
process.on('SIGTERM', async () => {
  await shutdown();
  process.exit(0);
});

프리로드 바이너리 (코드 변경 없음)

애플리케이션 코드를 건드리지 않고 계측하려면 Node의 -r 플래그로 SDK를 프리로드하세요.

node -r @sophonz/node-sdk/build/bin/opentelemetry-instrument.js app.js

또는 번들된 CLI를 사용합니다.

opentelemetry-instrument app.js

이 방식에서는 설정이 환경 변수(SOPHONZ_API_KEY, OTEL_SERVICE_NAME 등 설정 문서에 정리된 변수들)에서 옵니다.

다음 단계

• 설정 — 모든 SDKConfig 옵션과 환경 변수.
• 미들웨어 — Express와 Koa에서 요청 스팬 보강하기.
• API 레퍼런스 — 노출된 함수와 제공되는 공식 OpenTelemetry API.
• 예제 — 완전한 Express와 Koa 서버 예제.