API 레퍼런스

Sophonz Node.js SDK 공개 API — init, shutdown, 미들웨어, 에러 핸들러, 트레이스 속성, 로거 트랜스포트, 제공되는 공식 OpenTelemetry API.

라이프사이클

init(config?): void

권장 진입점. 콘솔 캡처, 예외 캡처, Sentry 통합, 프로그래밍 방식 import 등 Sophonz 기본값에 사용자 SDKConfig 설정을 병합해 초기화합니다. 설정을 참고하세요.

initSDK(config): void

옵션별 기본값만 적용하는 저수준 초기화 함수입니다. 추가 동작이 없으므로 완전한 제어가 필요할 때 사용하세요.

shutdown(): Promise<void>

SDK를 정상 종료하고 대기 중인 텔레메트리를 모두 플러시합니다. stopOnTerminationSignals가 false가 아니면 SIGTERM / SIGINT 시 자동 호출됩니다.

import { init, shutdown } from '@sophonz/node-sdk';
 
init({ service: 'my-app' });
// ...
await shutdown();

미들웨어

sophonzExpressMiddleware(options?): RequestHandler

활성 스팬과 가변 트레이스 컨텍스트에 baggage, 클라이언트 IP, user-agent, 사용자 지정 속성을 추가하는 Express 요청 미들웨어입니다. 미들웨어를 참고하세요.

sophonzKoaMiddleware(options?): Middleware

sophonzExpressMiddleware의 Koa 버전입니다.

둘 다 SophonzMiddlewareOptions(captureBaggage, captureClientIp, captureUserAgent, attributes)를 받습니다.

에러 처리

setupExpressErrorHandler(app): void

오류(기본적으로 상태 >= 500)를 기록하는 Express 에러 처리 미들웨어를 등록합니다. 라우트 뒤에 호출하세요.

setupKoaErrorHandler(app): void

Koa 미들웨어 체인을 try/catch로 감싸 throw된 오류를 기록합니다.

recordException(error, hint?): Promise<void>

예외를 수동으로 기록합니다. 선택적 hint는 { tracer?, span?, attributes?, ... }와 표준 이벤트 힌트 필드를 받습니다.

import { recordException } from '@sophonz/node-sdk';
 
await recordException(err, { attributes: { 'job.name': 'nightly-sync' } });

트레이스 속성

setTraceAttributes(attributes): void

가변 async-local 트레이스 컨텍스트에 속성을 설정해 같은 요청에서 이후 생성되는 스팬으로 전파합니다. 프레임워크 미들웨어가 내부적으로 사용하는 방식입니다.

import { setTraceAttributes } from '@sophonz/node-sdk';
 
setTraceAttributes({ 'enduser.id': userId });

로거 트랜스포트

기존 로거를 Sophonz 로그로 연결합니다.

import { getWinstonTransport, getPinoTransport } from '@sophonz/node-sdk';
 
// Winston
logger.add(getWinstonTransport('info'));
 
// Pino
const transport = getPinoTransport('info');

Pino 로그 레코드에 트레이스 컨텍스트를 추가하는 getPinoMixinFunction도 노출됩니다.

디버깅

enableDebugPayloadExporters(): Promise<void>

초기화된 프로바이더에 콘솔 익스포터를 붙여 OTLP 익스포터와 함께 모든 스팬·로그 레코드를 터미널에 출력합니다. init / initSDK 이후에 호출하세요.

import { init, enableDebugPayloadExporters } from '@sophonz/node-sdk';
 
init({ service: 'my-app' });
if (process.env.SOPHONZ_DEBUG_PAYLOAD === 'true') {
  void enableDebugPayloadExporters();
}

GCP

registerGCPCloudFunctionEventHandler(...)

Google Cloud Function 이벤트 핸들러 계측을 위한 헬퍼입니다.

공식 OpenTelemetry API

SDK는 최신 안정화 버전의 공식 @opentelemetry/api와 @opentelemetry/api-logs API 도구를 함께 제공합니다. SDK에서 import하세요.

import { trace, context, propagation, metrics, logs } from '@sophonz/node-sdk';
 
const span = trace.getActiveSpan();
span?.setAttribute('cart.size', items.length);

사용 가능한 값: context, diag, metrics, propagation, trace, ProxyTracerProvider, SpanKind, SpanStatusCode, ValueType, createContextKey, isSpanContextValid, isValidSpanId, isValidTraceId, logs, SeverityNumber.

사용 가능한 타입: Attributes, AttributeValue, Baggage, BaggageEntry, Context, Counter, Histogram, Meter, Span, SpanContext, SpanOptions, TextMapPropagator, Tracer, TracerProvider, OtelApiLogger, LogRecord.