@imqa/instrumentation-node

개요

@imqa/instrumentation-node는 Node.js 환경에서 OpenTelemetry 기반의 자동 계측을 제공합니다.
이 모듈은 @sentry/node와 연동하여, Node.js 애플리케이션의 트레이싱 및 성능 모니터링을 손쉽게 구현할 수 있도록 지원합니다.

OpenTelemetry JS API 및 SDK 1.0+ 버전과 호환됩니다.

설치

npm install --save @imqa/instrumentation-node

사용법

const {
  SentryNodeInstrumentation,
} = require('@imqa/instrumentation-node');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [new SentryNodeInstrumentation()],
});

스키마 구조

이 모듈은 OpenTelemetry 스팬(Span) 기반으로 Node.js 애플리케이션의 주요 동작을 추적합니다.

주요 스팬

• SentryNodeInstrumentation 스팬
  Node.js 애플리케이션의 주요 트랜잭션 및 이벤트를 추적하는 스팬입니다.
  • traceId: 트레이스의 고유 식별자
  • spanId: 스팬의 고유 식별자
  • name: 스팬 이름 (예: "http.request", "db.query" 등)
  • kind: 스팬의 타입 (SERVER, CLIENT, INTERNAL 등)
  • startTimeUnixNano: 스팬 시작 시간 (나노초)
  • endTimeUnixNano: 스팬 종료 시간 (나노초)
  • status: 결과 상태 (0 = OK, 1 = ERROR, 2 = UNSET)

스팬 속성

각 스팬은 다음과 같은 공통 속성을 포함할 수 있습니다:

| 속성 | 타입 | 설명 | |-----------|------|-------------| | service.name | string | 서비스 이름 | | environment | string | 환경 이름 (예: "production", "development") | | deployment.environment | string | 배포 환경 | | http.method | string | HTTP 요청 메서드 | | http.url | string | 요청 URL | | http.status_code | integer | HTTP 응답 코드 | | db.system | string | 데이터베이스 종류 (예: "mysql", "postgresql") | | db.statement | string | 실행된 쿼리문 | | component | string | 계측 컴포넌트 (예: "sentry-node") |

이벤트

스팬에는 다양한 이벤트가 기록될 수 있습니다. 예를 들어:

| 이벤트 | 설명 | |-------|-------------| | exception | 예외 발생 시 기록 | | log | 로그 이벤트 기록 | | request | HTTP 요청 시작 | | response | HTTP 응답 완료 |

계측 설정

(boolean 또는 SentryNodeInstrumentationConfig, 선택)

계측 활성화 여부 및 세부 설정을 지정할 수 있습니다.

interface SentryNodeInstrumentationConfig
  extends InstrumentationConfig {
  ignoreUrls?: (string | RegExp)[];
  captureHttpHeaders?: boolean;
}

• ignoreUrls: 계측하지 않을 URL 패턴 지정 (정규식 또는 문자열 배열)
• captureHttpHeaders: HTTP 헤더 캡처 여부

유용한 링크

• OpenTelemetry 공식 사이트: https://opentelemetry.io/
• OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js

라이센스

Copyright (c) 2024-2025 ONYCOM CO., LTD. All rights reserved.