2nd/10_Wiki/Topic_Programming/Coding/Observability_OpenTelemetry.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
observability-opentelemetry	OpenTelemetry — 통합 추적/메트릭/로그	Coding	draft	B	conceptual	2026-05-09	2026-05-09	observability opentelemetry tracing vibe-coding	language applicable_to TypeScript / OpenTelemetry SDK Backend		otel distributed tracing span instrumentation

OpenTelemetry

Vendor 중립 표준. 한 SDK 로 trace + metrics + logs 수집 → OTLP → Jaeger / Tempo / Datadog / Honeycomb 어디든. auto-instrumentation 으로 80% 무료, 비즈니스 span 만 직접.

📖 핵심 개념

• Trace: 요청 1건이 만든 span 트리.
• Span: 한 작업 (HTTP, DB query, function call).
• Context propagation: trace-id / span-id 가 외부 호출 / 큐로 이어짐.
• Resource: service name / version / instance.
• Exporter: OTLP gRPC/HTTP 가 표준.

💻 코드 패턴

Node 부팅 시 셋업

// telemetry.ts (앱 import 보다 먼저)
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-proto';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { Resource } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'user-service',
    [ATTR_SERVICE_VERSION]: process.env.GIT_SHA,
  }),
  traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }),
    exportIntervalMillis: 30_000,
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', () => sdk.shutdown());

node --require ./telemetry.ts app.ts 로 실행.

자동으로 잡히는 것:

• HTTP server / client
• Express / Fastify / Koa
• pg / mysql / redis
• aws-sdk
• gRPC

비즈니스 span 직접

import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer('user-service');

async function processOrder(orderId: string) {
  return tracer.startActiveSpan('order.process', async (span) => {
    span.setAttribute('order.id', orderId);
    try {
      const o = await fetchOrder(orderId);     // 자동 child span
      await chargePayment(o);                  // 자동 child span
      span.setAttribute('order.amount', o.total);
      return o;
    } catch (e) {
      span.recordException(e as Error);
      span.setStatus({ code: 2 /* ERROR */ });
      throw e;
    } finally {
      span.end();
    }
  });
}

Span 안의 baggage (메타데이터 전파)

import { propagation, context } from '@opentelemetry/api';

const baggage = propagation.createBaggage({
  user_id: { value: userId },
  feature_flag_x: { value: 'on' },
});
context.with(propagation.setBaggage(context.active(), baggage), () => {
  // 이 안의 모든 외부 호출이 user_id 전파
});

🤔 의사결정 기준

도입 단계	권장
모놀리스 단일 서비스	auto-instrumentation 만
마이크로서비스 (>3)	auto + 비즈니스 span
매우 큰 트래픽 (비용)	head sampling (1%) + tail sampling (errors)
Lambda / Edge	OpenTelemetry Lambda Layer
자체 인프라	OpenTelemetry Collector + Tempo/Jaeger
SaaS (Datadog/Honeycomb)	OTLP 호환

❌ 안티패턴

• 모든 함수에 span: 폭증. 큰 단위 (request, transaction, queue job).
• span attribute 에 PII: 같은 redact 정책. 민감 X.
• 수동 trace-id 전파: SDK 가 자동. 직접 설정 시 충돌.
• sampling 100% prod: 비용 폭증. 1-10% + tail sampling for errors.
• resource attribute 없음: 어떤 서비스 / 버전인지 모름.
• shutdown 누락: deploy 시 마지막 span 손실. SIGTERM handler.
• 로그와 trace 별개: trace_id 를 로그에 같이 출력 → exemplar 로 그래프 점프.

🤖 LLM 활용 힌트

• "auto-instrumentation 먼저, 비즈니스 span 만 직접" 명시.
• service.name / version / env 리소스 필수.
• shutdown handler.

🔗 관련 문서

• Observability_Correlation_IDs
• Observability_RED_USE_Metrics