OpenTelemetry로 Node.js 분산 트레이싱 시작하기: 장애 원인 10분 안에 찾는 실무 가이드

장애가 났을 때 가장 답답한 순간은 “느리다”는 사실만 알고 어디가 병목인지 모를 때입니다. Node.js 서비스에서 OpenTelemetry 기반 분산 트레이싱을 도입하면, 요청 하나가 여러 서비스와 DB를 거치는 경로를 Trace ID 하나로 따라가며 원인을 빠르게 좁힐 수 있습니다.

왜 지금 Node.js 분산 트레이싱이 필요한가

로그와 메트릭만으로는 경로 단위 원인 파악이 어렵다

메트릭은 이상 징후를 빨리 발견하는 데 강하고, 로그는 개별 이벤트 확인에 좋습니다. 하지만 “A API 호출이 왜 3초가 걸렸는지”처럼 요청 경로 단위 분석은 트레이스가 가장 효율적입니다.

온콜 대응 시간을 줄이는 가장 현실적인 투자다

분산 트레이싱의 핵심 효과는 화려한 대시보드가 아니라 장애 상황에서 평균 원인 파악 시간(MTTI)을 줄이는 데 있습니다.

OpenTelemetry 적용 전 최소 설계 체크

1) 추적할 핵심 사용자 경로부터 정한다

처음부터 모든 엔드포인트를 완벽히 커버하려고 하면 운영 부담이 커집니다. 먼저 비즈니스 임팩트가 큰 경로부터 시작하세요.

로그인
결제
검색/추천

2) Trace ID를 로그와 함께 남기도록 규칙화한다

트레이싱만 있고 로그 연계가 없으면 현장에서 불편합니다. 애플리케이션 로그에 trace_id, span_id를 함께 남겨서 트레이스 ↔ 로그를 양방향으로 탐색할 수 있게 만드세요.

3) 샘플링 정책을 트래픽 규모에 맞춘다

트레이스 100% 수집은 비용이 빠르게 증가합니다. 실무에서는 보통 아래 전략이 안정적입니다.

기본: 5~10% 확률 샘플링
오류 요청: 강제 100% 수집
고가치 경로(결제 등): 별도 상향 샘플링

Node.js(Express)에서 OpenTelemetry 빠르게 붙이기

의존성 설치

npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

부트스트랩 코드 예시

// tracing.js
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const traceExporter = new OTLPTraceExporter({
  // 예: http://otel-collector:4318/v1/traces
  url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
});

const sdk = new NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', async () => {
  await sdk.shutdown();
  process.exit(0);
});

// server.js
import './tracing.js';
import express from 'express';

const app = express();
app.get('/health', (_, res) => res.send('ok'));
app.listen(3000);

핵심은 앱 시작 전에 tracing bootstrap을 먼저 로드하는 것입니다. 그래야 HTTP/DB/외부 호출 계측이 자동으로 붙습니다.

운영에서 자주 막히는 포인트

Trace ID는 있는데 서비스 간 연결이 끊기는 경우

원인은 대부분 프록시/게이트웨이 계층에서 헤더 전파가 누락되는 문제입니다. W3C Trace Context(traceparent)를 중간 계층이 유지하도록 확인해야 합니다.

대시보드는 있는데 알림 규칙이 없는 경우

트레이싱은 탐색 도구이고, 탐지를 대체하지 않습니다. p95 지연시간 급등, 오류율 증가 같은 메트릭 알림과 함께 써야 효과가 큽니다.

Collector 장애를 고려하지 않은 경우

Collector가 단일 장애점이 되지 않도록 버퍼링/재시도/수평 확장 전략을 미리 준비하세요.

실무 적용 체크리스트

배포 전

핵심 경로 2~3개에 대해 trace 확인
로그에 trace_id/span_id 노출 확인
샘플링 정책 문서화

배포 후 1주일

상위 지연 스팬 Top 10 점검
오류 트레이스 재현 가능성 점검
온콜 회고에 트레이스 활용 사례 기록

요약

Node.js에서 OpenTelemetry 분산 트레이싱은 “관측 데이터가 많아졌는데도 원인 파악이 느린” 팀을 가장 빠르게 개선하는 방법입니다. 작게 시작해 핵심 경로부터 트레이스를 안정화하면, 장애 대응 속도와 배포 자신감이 함께 올라갑니다.