OpenTelemetry 실전 가이드 — Node.js·Python 트레이싱 설정, Jaeger 연동, 프로덕션 관측가능성 구축

npm 패키지 설치
# 기본 SDK와 자동 계측
npm install @opentelemetry/sdk-node
npm install @opentelemetry/auto-instrumentations-node

# OTLP 익스포터 (gRPC 방식 — Jaeger·Collector 전송용)
npm install @opentelemetry/exporter-trace-otlp-grpc
npm install @opentelemetry/exporter-metrics-otlp-grpc
npm install @grpc/grpc-js

instrumentation.js — 계측 초기화 파일
// instrumentation.js
'use strict';
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { Resource } = require('@opentelemetry/resources');
const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'my-service',
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
    }),
    exportIntervalMillis: 10_000, // 10초마다 메트릭 전송
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-http': { enabled: true },
      '@opentelemetry/instrumentation-express': { enabled: true },
      '@opentelemetry/instrumentation-pg': { enabled: true },
    }),
  ],
});

sdk.start();

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

package.json — 계측 파일을 먼저 로드하는 시작 스크립트
{
  "scripts": {
    "start": "node --require ./instrumentation.js src/index.js",
    "dev": "nodemon --require ./instrumentation.js src/index.js"
  }
}

requirements.txt — Python 의존성
opentelemetry-sdk==1.25.0
opentelemetry-instrumentation-fastapi==0.46b0
opentelemetry-instrumentation-httpx==0.46b0
opentelemetry-instrumentation-sqlalchemy==0.46b0
opentelemetry-exporter-otlp-proto-grpc==1.25.0

telemetry.py — FastAPI 계측 초기화
# telemetry.py
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

def setup_telemetry(app):
    resource = Resource.create({
        SERVICE_NAME: os.getenv("OTEL_SERVICE_NAME", "fastapi-service"),
    })
    exporter = OTLPSpanExporter(
        endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"),
    )
    provider = TracerProvider(resource=resource)
    provider.add_span_processor(BatchSpanProcessor(exporter))
    trace.set_tracer_provider(provider)
    FastAPIInstrumentor.instrument_app(app)
    HTTPXClientInstrumentor().instrument()

main.py — FastAPI 앱 진입점
# main.py
from fastapi import FastAPI
from telemetry import setup_telemetry

app = FastAPI()
setup_telemetry(app)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    return {"item_id": item_id, "name": "예제 아이템"}

docker-compose.yml — 로컬 Jaeger 구성
version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:1.56
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "16686:16686"   # Jaeger UI
      - "4317:4317"     # OTLP gRPC
      - "4318:4318"     # OTLP HTTP
    restart: unless-stopped

  api:
    build: .
    environment:
      - OTEL_SERVICE_NAME=my-express-api
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
    depends_on:
      - jaeger
    ports:
      - "3000:3000"

Node.js — 커스텀 스팬과 속성 추가
// Node.js 커스텀 스팬 예제
const { trace, SpanStatusCode } = require('@opentelemetry/api');
const tracer = trace.getTracer('payment-service');

async function processPayment(userId, amount) {
  return tracer.startActiveSpan('payment.process', async (span) => {
    try {
      // 비즈니스 속성 추가
      span.setAttribute('user.id', userId);
      span.setAttribute('payment.amount', amount);
      span.setAttribute('payment.currency', 'KRW');

      const result = await chargeCard(userId, amount);

      span.setAttribute('payment.transaction_id', result.transactionId);
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (err) {
      span.recordException(err);
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
      throw err;
    } finally {
      span.end();
    }
  });
}

Python — 커스텀 스팬과 속성
# Python 커스텀 스팬 예제
from opentelemetry import trace
from opentelemetry.trace import StatusCode

tracer = trace.get_tracer("payment-service")

async def process_payment(user_id: str, amount: int):
    with tracer.start_as_current_span("payment.process") as span:
        span.set_attribute("user.id", user_id)
        span.set_attribute("payment.amount", amount)
        span.set_attribute("payment.currency", "KRW")
        try:
            result = await charge_card(user_id, amount)
            span.set_attribute("payment.transaction_id", result["id"])
            span.set_status(StatusCode.OK)
            return result
        except Exception as e:
            span.record_exception(e)
            span.set_status(StatusCode.ERROR, str(e))
            raise

otel-collector-config.yaml — 기본 Collector 설정
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

  memory_limiter:
    check_interval: 1s
    limit_mib: 512
    spike_limit_mib: 128

  # 헬스체크 요청은 트레이스에서 제외
  filter/drop-health:
    traces:
      span:
        - 'attributes["http.route"] == "/health"'

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

  prometheus:
    endpoint: "0.0.0.0:8889"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter/drop-health, batch]
      exporters: [otlp/jaeger]

    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [prometheus]

Node.js — 커스텀 카운터와 히스토그램
// 커스텀 메트릭 예제 (Node.js)
const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('payment-service');

// 카운터 — 결제 시도 횟수 누적
const paymentCounter = meter.createCounter('payment.total', {
  description: '총 결제 시도 횟수',
});

// 히스토그램 — P50/P95/P99 레이턴시 분포
const paymentDuration = meter.createHistogram('payment.duration', {
  description: '결제 처리 시간 (밀리초)',
  unit: 'ms',
});

async function processPayment(userId, amount) {
  const startTime = Date.now();
  try {
    const result = await chargeCard(userId, amount);
    paymentCounter.add(1, { 'payment.method': 'card', status: 'success' });
    return result;
  } catch (err) {
    paymentCounter.add(1, { 'payment.method': 'card', status: 'error' });
    throw err;
  } finally {
    paymentDuration.record(Date.now() - startTime, {
      'payment.method': 'card',
    });
  }
}