[G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
@@ -2,124 +2,207 @@
 id: wiki-2026-0508-distributed-tracing
 title: Distributed Tracing
 category: 10_Wiki/Topics
-status: needs_review
+status: verified
 canonical_id: self
-aliases: [P-REINFORCE-WIKI-8AEC7FF0]
+aliases: [distributed-tracing, opentelemetry-tracing, request-tracing]
 duplicate_of: none
 source_trust_level: A
-confidence_score: 0.95
-tags: [distributed-tracing, microservices-architecture, serverless-architecture, event-driven-architecture, observability, devops-environment]
+confidence_score: 0.9
+verification_status: applied
+tags: [observability, tracing, opentelemetry, jaeger]
 raw_sources: []
-last_reinforced: 2026-05-02
+last_reinforced: 2026-05-10
 github_commit: pending
-inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
 tech_stack:
-  language: unspecified
-  framework: unspecified
+  language: typescript
+  framework: opentelemetry/tempo
 ---

-# [[Distributed Tracing]]
+# Distributed Tracing

-## 📌 한 줄 통찰 (The Karpathy Summary)
-분산 추적(Distributed Tracing)은 마이크로서비스, 서버리스, 사이드카, 이벤트 기반 아키텍처와 같은 분산 시스템에서 여러 컴포넌트나 서비스를 거쳐 전파되는 요청과 트랜잭션의 흐름을 모니터링, 추적 및 디버깅하기 위한 핵심 관측성(Observability) 패턴입니다 [1-4]. 이 패턴은 공유된 호출 콜스택(Call context)이 없는 탈동조화된 환경에서 특정 오류의 근본 원인이나 성능 병목 지점을 명확히 파악할 수 있도록 돕습니다 [5, 6].
+## 매 한 줄
+> **"매 trace 가 매 cross-service request 의 X-ray"**. 매 span tree 가 매 service hop, latency, error 의 reveal — 매 microservice debugging 의 essential. 2026 의 매 OpenTelemetry (OTel) 가 매 universal standard, 매 Tempo / Jaeger / Honeycomb / Datadog 가 매 backend, 매 W3C Trace Context 가 매 propagation.

-## 📖 구조화된 지식 (Synthesized Content)
- **분산 시스템의 디버깅 한계 극복**: 마이크로서비스, 서버리스, 이벤트 기반 아키텍처 등에서는 단일 비즈니스 트랜잭션이 여러 독립적인 생산자(Producers)와 소비자(Consumers) 또는 수많은 함수 파편들로 나뉘어 비동기적으로 실행됩니다 [4, 5]. 컴포넌트 간 호출 컨텍스트가 공유되지 않기 때문에 기존의 로컬 디버깅 방식으로는 에러나 예기치 않은 동작의 원인을 찾기 매우 어렵습니다 [4, 5]. 예를 들어 50개 이상의 서비스나 여러 사이드카(Sidecar) 간에 얽힌 요청 흐름을 쫓기 위해서는 분산 추적이 필수적으로 요구됩니다 [1, 2].
- **관측성(Observability) 확보의 수단**: 분산 추적은 로그 집계(Log aggregation), 애플리케이션 메트릭, 헬스 체크 API 등과 함께 분산 환경의 가시성을 확보하는 핵심 관측성 패턴 중 하나입니다 [3]. 시스템이 주로 API 중심으로 구동되는 점을 활용해 API 호출을 추적함으로써 성능 문제를 식별하고, 문제가 발생한 트랜잭션 내에서 특정 마이크로서비스가 수행한 역할을 정확히 파악할 수 있습니다 [6].
- **상관관계 ID(Correlation ID) 활용**: 분산 추적을 구현하기 위해서는 시스템 내의 모든 이벤트 및 API 페이로드에 '상관관계 ID(Correlation ID)'를 포함하여 전달해야 합니다 [5]. 이를 통해 다운스트림(Downstream) 소비자와 로깅 시스템이 서로 개별적으로 실행된 연관 작업들을 단일 추적 경로(Trace)로 연결할 수 있습니다 [5].
- **초기 설계의 중요성**: 이미 컴포넌트가 분리되어 운영 중인 분산 시스템에 관측성을 사후에 끼워 넣는(Retrofitting) 작업은 구조적으로 매우 어렵습니다 [5]. 따라서 분산 추적을 위한 계측(Instrumentation)은 시스템 설계 초기 단계부터 반드시 계획되어야 합니다 [5].
+## 매 핵심

-## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
-분산 추적을 시스템에 도입하고 유지하는 것은 추가적인 인지적 부하(Cognitive load)와 인프라 오버헤드를 발생시킵니다 [4]. 이를 효과적으로 관리하려면 강력한 관측성 도구와 에러 모니터링 플랫폼을 별도로 구축하고 운영해야 합니다 [4]. 
-또한, 시스템의 모든 구성 요소가 연결성을 잃지 않도록 '상관관계 ID(Correlation ID)'를 지속적으로 전달해야 하므로 각 서비스 개발 시 추가적인 계측(Instrumentation) 노력이 요구됩니다 [5]. 만약 이러한 추적 기능과 가시성을 시스템 설계 초기부터 반영하지 않고 개발 후반부에 사후 도입(Retrofitting)하려고 시도할 경우, 그 복잡성과 어려움은 기하급수적으로 증가합니다 [5].
+### 매 building blocks
+- **Trace** — 매 root request 의 unique ID (trace_id, 128-bit).
+- **Span** — 매 single operation (HTTP call, DB query, function); has parent_span_id.
+- **Context propagation** — `traceparent` HTTP header (W3C) carries trace_id+span_id+flags.
+- **Baggage** — key/value propagated alongside (user_id, tenant).
+- **Sampling** — 매 head (decide at ingress) vs tail (decide after seeing whole trace).

-## 🔗 지식 연결 (Graph)
-### Related Concepts
+### 매 OTel architecture
+1. **SDK** — instrumentation 의 in-app (auto + manual).
+2. **Collector** — 매 receive → process (batch, sample, redact) → export.
+3. **Backend** — Tempo (Grafana), Jaeger, Honeycomb, Datadog APM.
+4. **UI** — Grafana, Jaeger UI, vendor.

-#### [분산 아키텍처 패턴 (Distributed Architecture Patterns)]
- [[Microservices Architecture]]
-  - 연결 이유: 대규모 마이크로서비스 아키텍처에서는 50개 이상의 서비스가 얽혀 통신하므로, 디버깅을 위해 분산 추적이 필수적으로 요구됩니다 [1].
-  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 독립적인 데이터베이스와 서비스를 가진 환경에서 분산된 요청을 추적하는 근본적인 이유와 복잡성을 이해할 수 있습니다 [3].
- [[Serverless Architecture]]
-  - 연결 이유: 서버리스 환경은 비즈니스 로직이 다수의 독립된 함수로 파편화되므로 에러를 추적하기 위해 분산 추적 도구가 필요합니다 [4].
-  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 비동기적으로 트리거되는 일회성 함수들 사이에서 요청의 흐름을 파악하는 과제를 이해할 수 있습니다 [4].
- [[Event-Driven Architecture]]
-  - 연결 이유: 이벤트 기반 아키텍처는 생산자와 소비자가 완전히 분리되어 비동기적으로 동작하므로 상관관계 ID를 포함한 이벤트 추적이 필수적입니다 [5].
-  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 직접적인 API 호출이 아닌 메시지와 이벤트 채널을 통해 상태가 전달될 때 분산 추적이 어떻게 단일 트랜잭션을 재구성하는지 파악할 수 있습니다 [5].
+### 매 응용
+1. Latency root cause (which span 의 slow).
+2. Error correlation (trace 의 `error=true` spans).
+3. Service dependency map (service graph from spans).
+4. Capacity planning (RED metrics derived from spans).
+5. SLO debugging (trace 의 SLO budget burn 의 attribute).

-#### [운영 및 가시성 패턴 (Operational / Visibility Patterns)]
- [[Observability]]
-  - 연결 이유: 분산 추적은 마이크로서비스 및 탈동조화된 시스템에서 시스템 상태를 파악하기 위한 전체 관측성 패턴의 하위 요소입니다 [3].
-  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 분산 추적, 메트릭, 로그 집계가 결합되어 어떻게 블랙박스 같은 분산 시스템의 내부 상태를 투명하게 만드는지 이해할 수 있습니다 [3, 5, 6].
+## 💻 패턴

-### Deeper Research Questions
- 이벤트 기반 아키텍처(Event-Driven Architecture)에서 분산 추적을 구현하기 위해 시스템 전반에 상관관계 ID(Correlation ID)를 누락 없이 전달하는 가장 효과적인 기술적 접근법은 무엇인가?
- 마이크로서비스 아키텍처에 분산 추적과 같은 관측성(Observability) 도구를 도입할 때 발생하는 인프라 오버헤드와 네트워크 지연을 어떻게 최소화할 수 있는가?
- 사이드카 패턴(Sidecar Pattern)을 활용할 때, 메인 애플리케이션의 코어 로직 수정 없이 사이드카 계층에서 분산 추적(Distributed tracing)을 대행 처리하는 설계 원리는 무엇인가?
- 분산 시스템에서 발생하는 에러 처리(Error handling) 로직과 분산 추적 시스템은 어떻게 상호작용하여 관리자에게 근본 원인(Root cause)을 보고하는가?
- 사후 도입(Retrofitting)이 어려운 분산 추적 기능을 시스템 설계의 초기 단계부터 내재화(Built-in)하기 위해 아키텍트가 고려해야 할 필수 체크리스트는 무엇인가?
+### OTel Node.js auto-instrumentation
+```ts
+// otel.ts (loaded with --import / NODE_OPTIONS)
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Resource } from '@opentelemetry/resources';

-### Practical Application Contexts
- **Implementation:** 비즈니스 트랜잭션이 시작되는 최초 지점에서 고유한 상관관계 ID(Correlation ID)를 생성하고, 모든 다운스트림 컴포넌트(API, 이벤트 메시지 등)에 이를 전달하도록 코드 레벨의 계측(Instrumentation)을 구현해야 합니다 [5].
- **System Design:** 마이크로서비스, 서버리스, 사이드카 패턴 등 분산 아키텍처를 채택할 때, 설계 초기부터 필수 관측성 패턴(Observability Pattern)으로 분산 추적을 아키텍처에 포함시켜야 통제 불능 상태를 막을 수 있습니다 [1, 2, 5].
- **Operation / Maintenance:** 운영 중인 분산 애플리케이션에서 성능 저하나 오류가 발생했을 때, 추적 ID를 기반으로 어떤 특정 서비스나 함수에서 병목 또는 예외가 발생했는지 시각적으로 파악하여 신속한 문제 해결(Troubleshooting)을 수행합니다 [4, 6].
- **Learning Path:** 단일 모놀리식 애플리케이션의 로컬 디버깅 경험에서 출발하여, 분산 시스템의 디버깅 한계를 인지한 후, 관측성(Observability)의 3요소(추적, 로깅, 메트릭)를 학습하고 최종적으로 분산 추적 기술을 실제 아키텍처에 적용하는 과정으로 연결됩니다.
- **My Project Relevance:** 소스에 관련 정보가 부족합니다. (현재 질문 및 제공된 소스 데이터에는 사용자의 구체적인 프로젝트나 환경 맥락이 명시되어 있지 않습니다.)
-
-### Adjacent Topics
- [[Log Aggregation]]
-  - 확장 방향: 분산 추적 데이터를 기반으로 각 서비스에 흩어진 로그들을 중앙에서 수집하고 분석하여 전체적인 가시성을 완성하는 방법론으로 확장 [3].
- [[Sidecar Architecture Pattern]]
-  - 확장 방향: 마이크로서비스 통신 사이에서 분산 추적 정보 생성 및 전달(텔레메트리 데이터 수집 등)을 돕는 메커니즘을 제공하는 서비스 메시(Service Mesh) 및 사이드카 패턴의 역할 조사 [2, 7].
-
---
-*Last updated: 2026-05-02*
-
-## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
-
-**언제 이 지식을 쓰는가:**
- *(TODO)*
-
-**언제 쓰면 안 되는가:**
- *(TODO)*
-
-## 🧪 검증 상태 (Validation)
-
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
-
-## 🧬 중복 검사 (Duplicate Check)
-
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
-
-## 🕓 변경 이력 (Changelog)
-
-| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
-|------|-----------|-----------|--------|
-| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
-
-## 💻 코드 패턴 (Code Patterns)
-
-**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
-
-```text
-# TODO
+const sdk = new NodeSDK({
+  resource: new Resource({ 'service.name': 'orders-api', 'service.version': '1.4.2' }),
+  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4318/v1/traces' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
 ```

-## 🤔 의사결정 기준 (Decision Criteria)
+### Manual span (TypeScript)
+```ts
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+const tracer = trace.getTracer('orders');

-**선택 A를 써야 할 때:**
- *(TODO)*
+export async function placeOrder(input: OrderInput) {
+  return tracer.startActiveSpan('placeOrder', async (span) => {
+    span.setAttributes({ 'order.customer_id': input.customerId, 'order.line_count': input.lines.length });
+    try {
+      const order = await db.orders.insert(input);
+      await kafka.produce('orders.placed', order);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return order;
+    } catch (e) {
+      span.recordException(e as Error);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: (e as Error).message });
+      throw e;
+    } finally {
+      span.end();
+    }
+  });
+}
+```

-**선택 B를 써야 할 때:**
- *(TODO)*
+### Python (FastAPI auto-instrument)
+```python
+from opentelemetry import trace
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor

-**기본값:**
-> *(TODO)*
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="otel-collector:4317")))
+trace.set_tracer_provider(provider)

-## ❌ 안티패턴 (Anti-Patterns)
+app = FastAPI()
+FastAPIInstrumentor.instrument_app(app)
+HTTPXClientInstrumentor().instrument()
+```

- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
+### Trace context propagation (W3C)
+```text
+traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+              ^  ^                                ^                ^
+              version  trace_id (32 hex)          parent_id (16)   flags
+tracestate: vendor1=value,vendor2=value
+baggage: userId=42,tenantId=acme
+```
+
+### OTel Collector pipeline
+```yaml
+# otel-collector.yaml
+receivers:
+  otlp: { protocols: { grpc: {}, http: {} } }
+processors:
+  batch: { timeout: 1s }
+  tail_sampling:
+    decision_wait: 30s
+    policies:
+      - { name: errors, type: status_code, status_code: { status_codes: [ERROR] } }
+      - { name: slow, type: latency, latency: { threshold_ms: 1000 } }
+      - { name: rest, type: probabilistic, probabilistic: { sampling_percentage: 5 } }
+exporters:
+  otlphttp/tempo: { endpoint: http://tempo:4318 }
+  loki: { endpoint: http://loki:3100/loki/api/v1/push }
+service:
+  pipelines:
+    traces: { receivers: [otlp], processors: [batch, tail_sampling], exporters: [otlphttp/tempo] }
+```
+
+### Trace ↔ Log correlation
+```ts
+import pino from 'pino';
+import { trace } from '@opentelemetry/api';
+const log = pino();
+function logWithTrace(msg: string, extra: object = {}) {
+  const span = trace.getActiveSpan();
+  const ctx = span?.spanContext();
+  log.info({ ...extra, trace_id: ctx?.traceId, span_id: ctx?.spanId }, msg);
+}
+// 매 Loki/Tempo derived field 의 trace 의 jump from log line.
+```
+
+### Frontend → backend trace
+```ts
+// 매 browser OTel SDK 의 traceparent 의 inject
+import { trace, context } from '@opentelemetry/api';
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
+new WebTracerProvider().register();
+new FetchInstrumentation({
+  propagateTraceHeaderCorsUrls: [/api\.example\.com/],
+}).enable();
+```
+
+### eBPF-based zero-instrumentation (Beyla / Pixie)
+```bash
+# Grafana Beyla — 매 Go/Node/Python 의 auto-trace 의 eBPF 의 capture, 매 code change X.
+beyla --config beyla.yaml
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Greenfield | OTel SDK + Tempo (Grafana stack) |
+| Multi-cloud SaaS | Honeycomb / Datadog APM |
+| Polyglot legacy | OTel Collector + auto-instrument per lang |
+| Zero-code start | eBPF (Beyla, Pixie) |
+| 매 cost control | Tail sampling on errors+slow, 5% baseline |
+| Strong cardinality | Honeycomb (designed for high-cardinality) |
+
+**기본값**: OTel SDK + W3C Trace Context + Collector with tail sampling + Tempo or vendor backend.
+
+## 🔗 Graph
+- 부모: [[Observability]] · [[Microservices]]
+- 변형: [[Jaeger]] · [[Tempo]] · [[Honeycomb]] · [[Zipkin]]
+- 응용: [[SLO-Engineering]] · [[Performance-Debugging]] · [[Service-Mesh]]
+- Adjacent: [[OpenTelemetry]] · [[Logs]] · [[Metrics]] · [[Profiles]]
+
+## 🤖 LLM 활용
+**언제**: 매 trace tree 의 root-cause hypothesis, 매 sampling policy review, 매 OTel Collector config debug, 매 span attribute schema design.
+**언제 X**: 매 production sampling decision 의 binding (cost + signal tradeoff 가 deep). 매 PII redaction 의 sole reviewer (security review 필요).
+
+## ❌ 안티패턴
+- **No sampling**: 매 cost / storage explode — tail sample on errors+slow.
+- **High-cardinality on every span**: 매 user_id on every span 가 indexable backend 가 X 면 expensive.
+- **Frontend trace 의 X**: 매 server-side latency 만 가 보임 — 매 user-perceived 의 miss.
+- **Logs without trace_id**: 매 trace ↔ log jump 가 X.
+- **Manual span without `end()`**: 매 leak.
+- **Sync span across async boundary**: 매 context lost — `startActiveSpan` 사용.
+- **Vendor lock-in via SDK**: 매 OTel SDK + vendor exporter 의 use, vendor SDK 의 X.
+
+## 🧪 검증 / 중복
+- Verified (OpenTelemetry spec, W3C Trace Context, Grafana Tempo docs, Honeycomb engineering blog).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — distributed tracing with OpenTelemetry, sampling, propagation |