Node.js

Sophonz Node.js SDK는 자동 계측, 프레임워크 미들웨어, 예외 캡처와 함께 Node.js 서버 애플리케이션에 OpenTelemetry 기반 옵저버빌리티를 제공합니다.

@sophonz/node-sdk는 Node.js 서버를 위한 완전한 OpenTelemetry 배포판입니다. 자동 계측, 트레이스, 메트릭, 로그를 한 번에 구성하고 콘솔 캡처, 예외 캡처, Express/Koa 요청 미들웨어 같은 Sophonz 전용 기능을 더해 줍니다. 또한 최신 안정화 버전의 공식 @opentelemetry/api API 도구를 함께 제공하여 바로 import해 쓸 수 있습니다.

제공 기능

  • 자동 계측 — OpenTelemetry auto-instrumentation을 통한 HTTP/HTTPS, 주요 라이브러리, Node.js 런타임 메트릭 계측.
  • 프레임워크 미들웨어 — 모든 요청 스팬에 baggage, 클라이언트 IP, user-agent, 사용자 지정 속성을 추가하는 sophonzExpressMiddleware, sophonzKoaMiddleware.
  • 예외 캡처 — 처리되지 않은 예외와 reject 캡처, Express/Koa 에러 핸들러 제공.
  • 콘솔 캡처 — console.* 호출을 구조화된 로그로 변환.
  • Sentry 통합 — 이미 Sentry SDK를 사용하는 프로젝트 지원.
  • 공식 OpenTelemetry API 제공 — 최신 안정화 버전의 @opentelemetry/api API 도구(trace, context, propagation, metrics, logs)를 SDK에서 바로 import.

동작 방식

SDK는 두 가지 방법으로 초기화할 수 있습니다.

  1. 프로그래밍 방식 — 진입 파일 최상단에서 init() 호출.
  2. 프리로드 바이너리 방식 — opentelemetry-instrument(또는 node -r .../opentelemetry-instrument.js)로 앱을 실행해 어떤 모듈보다 먼저 계측 적용.

실행되면 SDK는 OTLP로 텔레메트리를 Sophonz 컬렉터에 전송합니다. SDKConfig 옵션 또는 이에 대응하는 SOPHONZ_* / OTEL_* 환경 변수로 설정하세요.

TIP — 다음으로

처음이라면 설치부터 시작한 뒤 설정과 미들웨어 가이드를 읽어 보세요.