OpenTelemetry로 마이크로서비스의 블랙박스를 해제하는 5가지 결정적 전략

사용자 요청의 여정 (일반적인 e-커머스)
============================================

[Client] ──▶ [API Gateway] ──▶ [Auth Service]
                  │
                  ├──▶ [Product Service] ──▶ [Search Engine]
                  │         │
                  │         └──▶ [Recommendation Service] ──▶ [ML Model]
                  │
                  ├──▶ [Cart Service] ──▶ [Redis Cache]
                  │
                  ├──▶ [Order Service] ──▶ [Inventory Service] ──▶ [Warehouse DB]
                  │         │
                  │         └──▶ [Payment Service] ──▶ [External PG API]
                  │
                  └──▶ [Notification Service] ──▶ [Email/SMS/Push]

하나의 "주문 완료"에 최소 12개 서비스가 관여한다.
p99 지연 원인을 찾으려면? 어디서부터 볼 것인가?

OpenTelemetry의 아키텍처 개요
============================================

  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
  │  Service A  │  │  Service B  │  │  Service C  │
  │  (Java SDK) │  │ (Python SDK)│  │  (Go SDK)   │
  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
         │ OTLP           │ OTLP           │ OTLP
         ▼                ▼                ▼
  ┌─────────────────────────────────────────────────┐
  │           OpenTelemetry Collector               │
  │  ┌──────────┐  ┌───────────┐  ┌──────────────┐ │
  │  │Receivers │→ │Processors │→ │  Exporters   │ │
  │  └──────────┘  └───────────┘  └──────────────┘ │
  └────────┬──────────────┬──────────────┬──────────┘
           │              │              │
           ▼              ▼              ▼
    ┌───────────┐  ┌───────────┐  ┌───────────┐
    │  Jaeger   │  │   Tempo   │  │  Datadog  │
    │ (Traces)  │  │ (Traces)  │  │ (All-in-1)│
    └───────────┘  └───────────┘  └───────────┘

import io.opentelemetry.api.baggage.Baggage;
import io.opentelemetry.api.baggage.BaggageEntryMetadata;
import io.opentelemetry.context.Scope;
import io.opentelemetry.api.trace.Span;

// ---- API Gateway에서 Baggage 설정 (요청 진입점) ----
@RestController
public class GatewayController {

    @PostMapping("/api/orders")
    public ResponseEntity<?> createOrder(
            @RequestHeader("X-Tenant-Id") String tenantId,
            @RequestHeader("X-User-Tier") String userTier,
            HttpServletRequest request) {

        // W3C Baggage 설정 - 다운스트림 서비스 전체에 전파됨
        Baggage baggage = Baggage.builder()
            .put("tenantId", tenantId,
                 BaggageEntryMetadata.create("tenant context"))
            .put("userTier", userTier,
                 BaggageEntryMetadata.create("qos context"))
            .put("entryPoint", "order-api",
                 BaggageEntryMetadata.create("routing context"))
            .put("requestRegion", determineRegion(request),
                 BaggageEntryMetadata.create("geo context"))
            .build();

        // Baggage를 현재 Context에 attach
        try (Scope scope = baggage.makeCurrent()) {
            // 이 scope 내에서 호출되는 모든 다운스트림 서비스는
            // 자동으로 baggage를 HTTP 헤더로 전파받음
            return orderService.processOrder(request.getBody());
        }
    }
}

// ---- 다운스트림 Order Service에서 Baggage 읽기 ----
@Service
public class OrderService {

    public void processOrder(OrderRequest order) {
        // 전파된 Baggage에서 비즈니스 컨텍스트 추출
        String tenantId = Baggage.current().getEntryValue("tenantId");
        String userTier = Baggage.current().getEntryValue("userTier");

        // 현재 Span에 비즈니스 속성으로 추가 (검색/필터링 용도)
        Span currentSpan = Span.current();
        currentSpan.setAttribute("business.tenant_id", tenantId);
        currentSpan.setAttribute("business.user_tier", userTier);

        // 사용자 등급에 따른 QoS 분기
        if ("premium".equals(userTier)) {
            processWithPriority(order);
        } else {
            processNormally(order);
        }
    }
}

from opentelemetry import baggage, trace, context
from opentelemetry.baggage.propagation import W3CBaggagePropagator
from opentelemetry.context.context import Context
from fastapi import FastAPI, Request, Header
from typing import Optional

app = FastAPI()
tracer = trace.get_tracer("order-service")

# ---- API Gateway에서 Baggage 설정 ----
@app.post("/api/orders")
async def create_order(
    request: Request,
    x_tenant_id: Optional[str] = Header(None),
    x_user_tier: Optional[str] = Header(None, alias="X-User-Tier"),
):
    # Baggage 설정
    ctx = baggage.set_baggage("tenantId", x_tenant_id or "unknown")
    ctx = baggage.set_baggage("userTier", x_user_tier or "standard", context=ctx)
    ctx = baggage.set_baggage("featureFlag", "new-checkout-v2", context=ctx)

    # Context를 활성화하여 다운스트림 호출에 자동 전파
    token = context.attach(ctx)
    try:
        with tracer.start_as_current_span("process-order") as span:
            # Baggage 값을 Span 속성으로도 기록
            tenant = baggage.get_baggage("tenantId")
            tier = baggage.get_baggage("userTier")
            span.set_attribute("business.tenant_id", tenant)
            span.set_attribute("business.user_tier", tier)

            result = await order_processor.process(request)
            return {"status": "created", "order_id": result.id}
    finally:
        context.detach(token)


# ---- 다운스트림 Inventory Service에서 Baggage 읽기 ----
@app.get("/api/inventory/{product_id}")
async def check_inventory(product_id: str, request: Request):
    # OTel SDK가 자동으로 HTTP 헤더에서 Baggage를 추출
    tenant_id = baggage.get_baggage("tenantId")
    user_tier = baggage.get_baggage("userTier")

    with tracer.start_as_current_span("check-inventory") as span:
        span.set_attribute("business.tenant_id", tenant_id)

        # 테넌트별 격리된 데이터소스 접근
        inventory = await get_tenant_inventory(tenant_id, product_id)
        return {"available": inventory.quantity > 0}

package main

import (
    "context"
    "net/http"

    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/baggage"
    "go.opentelemetry.io/otel/attribute"
)

var tracer = otel.Tracer("order-service")

// API Gateway에서 Baggage 설정
func CreateOrderHandler(c *gin.Context) {
    tenantID := c.GetHeader("X-Tenant-Id")
    userTier := c.GetHeader("X-User-Tier")

    // W3C Baggage 멤버 생성
    tenantMember, _ := baggage.NewMember("tenantId", tenantID)
    tierMember, _ := baggage.NewMember("userTier", userTier)
    flagMember, _ := baggage.NewMember("featureFlag", "new-checkout-v2")

    bag, _ := baggage.New(tenantMember, tierMember, flagMember)

    // Context에 Baggage 부착
    ctx := baggage.ContextWithBaggage(c.Request.Context(), bag)

    // 다운스트림 호출 시 자동 전파
    ctx, span := tracer.Start(ctx, "process-order")
    defer span.End()

    span.SetAttributes(
        attribute.String("business.tenant_id", tenantID),
        attribute.String("business.user_tier", userTier),
    )

    result, err := processOrder(ctx, c.Request.Body)
    if err != nil {
        span.RecordError(err)
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }
    c.JSON(http.StatusCreated, result)
}

// 다운스트림에서 Baggage 읽기
func processOrder(ctx context.Context, body io.ReadCloser) (*OrderResult, error) {
    bag := baggage.FromContext(ctx)
    tenantID := bag.Member("tenantId").Value()
    userTier := bag.Member("userTier").Value()

    ctx, span := tracer.Start(ctx, "validate-order")
    defer span.End()

    span.SetAttributes(
        attribute.String("business.tenant_id", tenantID),
    )

    // 비즈니스 로직 처리...
    return &OrderResult{ID: "ord-12345"}, nil
}

Baggage의 전파 경로와 보안 위험
============================================

[내부 서비스]  ──HTTP 헤더──▶  [내부 서비스]  ──HTTP 헤더──▶  [외부 API]
     │                              │                             │
     │  baggage: tenantId=acme,     │  baggage: tenantId=acme,    │  ⚠️ 외부로
     │  userId=12345,               │  userId=12345,              │  Baggage가
     │  email=user@acme.com         │  email=user@acme.com        │  유출됨!
     │                              │                             │
     └──────────────────────────────┘                             │
           Trust Boundary 내부             Trust Boundary 외부 ───┘

⚠️ Baggage는 평문 HTTP 헤더로 전송된다!
⚠️ PII(개인식별정보)를 절대 넣지 마라!

# OTel Collector에서 Baggage 필터링 설정 예시
processors:
  # 특정 baggage 키만 허용하는 attributes 프로세서
  attributes/baggage-filter:
    actions:
      # 허용된 비즈니스 키만 유지
      - key: baggage.tenantId
        action: upsert
      - key: baggage.userTier
        action: upsert
      # 민감한 키는 삭제
      - key: baggage.email
        action: delete
      - key: baggage.userId
        action: delete

자동 계측만으로 보이는 것 vs 실제로 알아야 하는 것
============================================

자동 계측이 캡처하는 Span:
  [POST /api/orders] ──▶ [SELECT * FROM products] ──▶ [POST /payments]
       200 OK, 1.2s          50ms                       800ms

보이는 정보: "주문 API가 1.2초 걸렸고, DB는 50ms, 결제는 800ms"
모르는 정보: 나머지 350ms는 어디서 소비되었는가?

실제로 그 350ms 안에서 일어나는 일:
  ├── 재고 가용성 검증 로직 (50ms)
  ├── 할인 쿠폰 적용 규칙 엔진 (120ms)     ← 이것이 병목!
  ├── 배송비 계산 로직 (30ms)
  ├── 사기 탐지(Fraud Detection) 점수 계산 (80ms)
  └── 주문 이벤트 직렬화 (70ms)

자동 계측은 이 350ms를 "비즈니스 로직" 이라는
하나의 불투명한 덩어리로만 보여준다.

# 1단계: 자동 계측 (JVM 에이전트 방식)
# OTel Java Agent 다운로드
curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

# JVM 시작 시 에이전트 첨부
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=order-service \
  -Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \
  -Dotel.exporter.otlp.protocol=grpc \
  -Dotel.resource.attributes=service.namespace=ecommerce,deployment.environment=production \
  -jar order-service.jar

// 2단계: 비즈니스 크리티컬 로직에 수동 Span 추가
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.common.Attributes;

@Service
public class OrderProcessingService {

    // 자동 계측 에이전트가 초기화한 글로벌 Tracer 사용
    private static final Tracer tracer =
        GlobalOpenTelemetry.getTracer("order-processing", "1.0.0");

    public OrderResult processOrder(OrderRequest request) {
        // 자동 계측: HTTP 진입 Span은 이미 생성되어 있음
        // 수동 계측: 비즈니스 로직의 세부 단계를 명시적으로 계측

        // 할인 적용 로직 계측
        Span discountSpan = tracer.spanBuilder("apply-discount-rules")
            .setAttribute("business.coupon_code", request.getCouponCode())
            .setAttribute("business.original_amount", request.getTotalAmount())
            .startSpan();

        try (var scope = discountSpan.makeCurrent()) {
            DiscountResult discount = discountEngine.calculate(request);
            discountSpan.setAttribute("business.discount_amount", discount.getAmount());
            discountSpan.setAttribute("business.discount_type", discount.getType());
            discountSpan.setAttribute("business.rules_evaluated", discount.getRulesCount());
        } catch (Exception e) {
            discountSpan.setStatus(StatusCode.ERROR, e.getMessage());
            discountSpan.recordException(e);
            throw e;
        } finally {
            discountSpan.end();
        }

        // 사기 탐지 계측
        Span fraudSpan = tracer.spanBuilder("fraud-detection")
            .setAttribute("business.user_id", request.getUserId())
            .setAttribute("business.order_amount", request.getTotalAmount())
            .startSpan();

        try (var scope = fraudSpan.makeCurrent()) {
            FraudScore score = fraudDetector.evaluate(request);
            fraudSpan.setAttribute("business.fraud_score", score.getValue());
            fraudSpan.setAttribute("business.fraud_decision", score.getDecision());

            if (score.getValue() > 0.8) {
                fraudSpan.addEvent("high-fraud-risk-detected",
                    Attributes.of(
                        AttributeKey.doubleKey("score"), score.getValue(),
                        AttributeKey.stringKey("reason"), score.getReason()
                    ));
            }
        } finally {
            fraudSpan.end();
        }

        // ...나머지 비즈니스 로직
    }
}

# 1단계: 자동 계측 패키지 설치
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install  # 감지된 라이브러리용 계측 패키지 자동 설치

# 2단계: 자동 계측으로 애플리케이션 실행
OTEL_SERVICE_NAME=order-service \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_RESOURCE_ATTRIBUTES=service.namespace=ecommerce,deployment.environment=production \
opentelemetry-instrument python -m uvicorn main:app --host 0.0.0.0 --port 8000

# 2단계: 비즈니스 로직에 수동 Span 추가
from opentelemetry import trace
from opentelemetry.trace import StatusCode

tracer = trace.get_tracer("order-processing", "1.0.0")

class OrderProcessor:
    async def process(self, order: OrderRequest) -> OrderResult:
        # 할인 로직 수동 계측
        with tracer.start_as_current_span(
            "apply-discount-rules",
            attributes={
                "business.coupon_code": order.coupon_code,
                "business.original_amount": order.total_amount,
            }
        ) as discount_span:
            try:
                discount = await self.discount_engine.calculate(order)
                discount_span.set_attribute("business.discount_amount", discount.amount)
                discount_span.set_attribute("business.rules_evaluated", discount.rules_count)
            except DiscountError as e:
                discount_span.set_status(StatusCode.ERROR, str(e))
                discount_span.record_exception(e)
                raise

        # 사기 탐지 수동 계측
        with tracer.start_as_current_span("fraud-detection") as fraud_span:
            score = await self.fraud_detector.evaluate(order)
            fraud_span.set_attribute("business.fraud_score", score.value)
            fraud_span.set_attribute("business.fraud_decision", score.decision)

            if score.value > 0.8:
                fraud_span.add_event("high-fraud-risk", attributes={
                    "score": score.value,
                    "reason": score.reason,
                })

        return await self._finalize_order(order, discount)

텔레메트리 볼륨 계산 예시
============================================

서비스 수: 30개
서비스당 평균 Span 수: 5개/요청
초당 요청 수(RPS): 10,000
Span당 평균 크기: 1 KB

초당 Span 수:  30 x 5 x 10,000 = 1,500,000 spans/sec
초당 데이터량: 1,500,000 x 1 KB = 1.5 GB/sec
일일 데이터량: 1.5 GB x 86,400 = ~130 TB/day

연간 저장 비용 (S3 기준): ~$35,000/month = ~$420,000/year
연간 Datadog 비용 (ingestion 기준): 수십배 이상

Tail-based Sampling을 위한 2-Tier Collector 아키텍처
============================================

  [Service A]   [Service B]   [Service C]   [Service D]
       │              │              │              │
       │  OTLP        │  OTLP        │  OTLP        │  OTLP
       ▼              ▼              ▼              ▼
  ┌──────────────────────────────────────────────────────┐
  │              Tier 1: Agent Collectors                │
  │            (DaemonSet, 각 노드에 1개)                 │
  │                                                      │
  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
  │  │ Agent 1  │  │ Agent 2  │  │ Agent 3  │           │
  │  │ (Node 1) │  │ (Node 2) │  │ (Node 3) │           │
  │  └────┬─────┘  └────┬─────┘  └────┬─────┘           │
  │       │              │              │                 │
  │       │   Load Balancing Exporter   │                 │
  │       │   (Trace ID 해시 기반)       │                 │
  └───────┼──────────────┼──────────────┼─────────────────┘
          │              │              │
          ▼              ▼              ▼
  ┌──────────────────────────────────────────────────────┐
  │           Tier 2: Gateway Collectors                 │
  │         (Deployment/StatefulSet, 수평 확장)           │
  │                                                      │
  │  ┌──────────────┐  ┌──────────────┐                  │
  │  │  Gateway 1   │  │  Gateway 2   │                  │
  │  │              │  │              │                  │
  │  │ Trace ID     │  │ Trace ID     │                  │
  │  │ a1xx → 여기  │  │ b2xx → 여기  │                  │
  │  │              │  │              │                  │
  │  │ tail_sampling │  │ tail_sampling │                  │
  │  │ processor    │  │ processor    │                  │
  │  └──────┬───────┘  └──────┬───────┘                  │
  └─────────┼──────────────────┼──────────────────────────┘
            │                  │
            ▼                  ▼
      ┌───────────┐     ┌───────────┐
      │  Backend  │     │  Backend  │
      │ (Tempo)   │     │ (Jaeger)  │
      └───────────┘     └───────────┘

# otel-collector-agent.yaml
# Tier 1: 각 노드에 DaemonSet으로 배포되는 Agent Collector

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  # 메모리 보호를 위한 리미터 (필수!)
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
    spike_limit_mib: 128

  # 기본 속성 추가 (노드 정보 등)
  resource:
    attributes:
      - key: k8s.node.name
        value: '${K8S_NODE_NAME}'
        action: upsert
      - key: deployment.environment
        value: 'production'
        action: upsert

  # 배치 처리 (네트워크 효율성)
  batch:
    send_batch_size: 1024
    send_batch_max_size: 2048
    timeout: 5s

exporters:
  # Trace ID 기반 로드 밸런싱 → Tier 2 Gateway로 전송
  loadbalancing:
    protocol:
      otlp:
        tls:
          insecure: true
    resolver:
      dns:
        hostname: otel-gateway-headless.observability.svc.cluster.local
        port: 4317

  # Metrics와 Logs는 직접 백엔드로 전송 (샘플링 불필요)
  otlp/metrics:
    endpoint: mimir.observability.svc.cluster.local:4317
    tls:
      insecure: true

  otlp/logs:
    endpoint: loki.observability.svc.cluster.local:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [loadbalancing] # Trace는 Gateway로 라우팅

    metrics:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [otlp/metrics] # Metrics는 직접 전송

    logs:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [otlp/logs] # Logs는 직접 전송

# otel-collector-gateway.yaml
# Tier 2: Tail-based Sampling을 수행하는 Gateway Collector

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 4096 # Gateway는 더 많은 메모리 필요
    spike_limit_mib: 1024

  # ⚠️ 중요: tail_sampling 전에 batch를 사용하지 마라!
  # batch가 같은 Trace의 Span을 분리할 수 있다.

  # Tail-based 샘플링 정책
  tail_sampling:
    # Trace 완료를 기다리는 시간
    # 시스템의 최대 예상 Trace 지속시간 + 네트워크 마진
    decision_wait: 30s
    # 결정 후 추가 Span을 기다리는 유예 시간
    num_traces: 100000 # 동시 추적할 최대 Trace 수
    expected_new_traces_per_sec: 1000

    policies:
      # 정책 1: 에러가 발생한 Trace는 100% 유지 (최우선)
      - name: errors-always-keep
        type: status_code
        status_code:
          status_codes:
            - ERROR

      # 정책 2: 높은 지연 시간의 Trace 유지 (p99 이상)
      - name: high-latency
        type: latency
        latency:
          threshold_ms: 5000 # 5초 이상 걸린 Trace

      # 정책 3: 특정 서비스의 Trace 항상 유지 (크리티컬 서비스)
      - name: critical-services
        type: string_attribute
        string_attribute:
          key: service.name
          values:
            - payment-service
            - order-service
          enabled_regex_matching: false

      # 정책 4: 프리미엄 사용자의 Trace 더 높은 비율로 유지
      - name: premium-users
        type: and
        and:
          and_sub_policy:
            - name: is-premium
              type: string_attribute
              string_attribute:
                key: business.user_tier
                values: ['premium', 'enterprise']
            - name: premium-rate
              type: probabilistic
              probabilistic:
                sampling_percentage: 50 # 50% 유지

      # 정책 5: 나머지 정상 Trace는 5%만 유지 (비용 최적화)
      - name: baseline-probabilistic
        type: probabilistic
        probabilistic:
          sampling_percentage: 5

  # tail_sampling 이후에 batch 적용
  batch:
    send_batch_size: 2048
    timeout: 10s

exporters:
  otlp/tempo:
    endpoint: tempo.observability.svc.cluster.local:4317
    tls:
      insecure: true

  otlp/jaeger:
    endpoint: jaeger-collector.observability.svc.cluster.local:4317
    tls:
      insecure: true

service:
  telemetry:
    metrics:
      address: 0.0.0.0:8888 # Collector 자체 메트릭 모니터링
    logs:
      level: info

  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, tail_sampling, batch]
      exporters: [otlp/tempo]

메모리 요구량 계산 공식
============================================

Required Memory (GB) =
  traces_per_second
  x decision_wait_seconds
  x avg_spans_per_trace
  x bytes_per_span
  / 1,000,000,000
  x safety_factor

예시 계산:
  traces_per_second     = 1,000
  decision_wait_seconds = 30
  avg_spans_per_trace   = 15
  bytes_per_span        = 1,000 (1 KB)
  safety_factor         = 2.0

  = 1,000 x 30 x 15 x 1,000 / 1,000,000,000 x 2.0
  = 450,000,000 / 1,000,000,000 x 2.0
  = 0.45 x 2.0
  = 0.9 GB

→ 최소 1 GB, 권장 2 GB 메모리 할당

표준 없이 각 팀이 자유롭게 명명한 속성들
============================================

팀 A (주문 서비스):     user_id="12345", status_code=200, method="POST"
팀 B (결제 서비스):     userId="12345",  httpStatus=200,  httpMethod="POST"
팀 C (재고 서비스):     uid="12345",     response_code=200, req_method="POST"
팀 D (알림 서비스):     customer_id="12345", http_code=200, verb="POST"
팀 E (검색 서비스):     user="12345",    code=200,        http.method="POST"

같은 사용자의 같은 요청인데 5가지 다른 속성명을 사용한다.
→ 서비스 간 상관 분석(Correlation) 불가!
→ 통합 대시보드 구축 불가!
→ 자동 알림 규칙 작성 불가!

Before (표준 없음):
  팀별로 다른 속성명 → 통합 쿼리 불가
  ─────────────────────────────────────
  Grafana에서 "모든 서비스의 5xx 에러율" 대시보드를 만들려면?

  Panel 1 (주문): rate({status_code=~"5.."})
  Panel 2 (결제): rate({httpStatus=~"5.."})
  Panel 3 (재고): rate({response_code=~"5.."})
  → 서비스마다 별도 쿼리 필요. 새 서비스 추가 시 대시보드 수정 필수.


After (Semantic Conventions 적용):
  모든 팀이 동일한 속성명 사용 → 단일 쿼리로 전체 조회
  ─────────────────────────────────────
  Grafana에서 "모든 서비스의 5xx 에러율" 대시보드:

  단일 쿼리: rate({http.response.status_code=~"5.."}) by (service.name)
  → 모든 서비스가 자동으로 포함. 새 서비스 추가 시 변경 없음.

Cross-Signal Correlation 워크플로우
============================================

1. Alert 발생:
   metric: http_server_request_duration_seconds{service.name="order-service"} > 5s

2. Trace에서 원인 추적:
   trace: service.name="order-service"
          AND http.response.status_code >= 500
          → Span에서 db.operation.name="SELECT",
            db.collection.name="orders" 확인

3. 관련 Log 조회:
   log: service.name="order-service"
        AND trace_id="abc123"
        → "Connection pool exhausted" 에러 로그 발견

모든 시그널에서 service.name, trace_id 등 동일한 속성명을 사용하기에
이 워크플로우가 자연스럽게 연결된다.

# Collector에서 속성명을 Semantic Conventions에 맞게 정규화
processors:
  # 레거시 속성명을 표준 속성명으로 변환
  attributes/normalize:
    actions:
      # HTTP 속성 정규화
      - key: http.method
        action: upsert
        from_attribute: httpMethod # 팀 B의 속성명
      - key: http.method
        action: upsert
        from_attribute: req_method # 팀 C의 속성명
      - key: http.method
        action: upsert
        from_attribute: verb # 팀 D의 속성명
      # 레거시 키 삭제
      - key: httpMethod
        action: delete
      - key: req_method
        action: delete
      - key: verb
        action: delete

      # 사용자 ID 정규화
      - key: enduser.id
        action: upsert
        from_attribute: user_id
      - key: enduser.id
        action: upsert
        from_attribute: userId
      - key: enduser.id
        action: upsert
        from_attribute: uid
      - key: enduser.id
        action: upsert
        from_attribute: customer_id
      # 레거시 키 삭제
      - key: user_id
        action: delete
      - key: userId
        action: delete
      - key: uid
        action: delete
      - key: customer_id
        action: delete

      # HTTP 상태 코드 정규화
      - key: http.response.status_code
        action: upsert
        from_attribute: status_code
      - key: http.response.status_code
        action: upsert
        from_attribute: httpStatus
      - key: http.response.status_code
        action: upsert
        from_attribute: response_code
      - key: http.response.status_code
        action: upsert
        from_attribute: http_code

  # 필수 리소스 속성이 누락된 경우 기본값 추가
  resource:
    attributes:
      - key: service.namespace
        value: 'default'
        action: insert # 이미 존재하면 덮어쓰지 않음
      - key: deployment.environment.name
        value: 'production'
        action: insert

# gRPC Exporter 설정 예시 (SDK)
# 환경변수 방식
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_TIMEOUT=10000

# Collector Receiver 설정 (gRPC)
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        max_recv_msg_size_mib: 16 # 최대 수신 메시지 크기
        max_concurrent_streams: 100 # 동시 스트림 수
        keepalive:
          server_parameters:
            max_connection_idle: 60s
            max_connection_age: 300s
            time: 30s
            timeout: 10s
        tls:
          cert_file: /certs/server.crt
          key_file: /certs/server.key
          client_ca_file: /certs/ca.crt # mTLS

# HTTP Exporter 설정 예시 (SDK)
# 환경변수 방식 (Protobuf)
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_TIMEOUT=10000

# HTTP JSON (디버깅 용도)
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

# Collector Receiver 설정 (HTTP)
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - 'https://*.example.com' # 브라우저 CORS 허용
          allowed_headers:
            - 'Content-Type'
            - 'X-Custom-Header'
          max_age: 7200
        tls:
          cert_file: /certs/server.crt
          key_file: /certs/server.key

OTLP 전송 방식 선택 의사결정 트리
============================================

시작: 텔레메트리 전송 방식을 선택해야 한다

Q1. 브라우저 또는 서버리스 환경인가?
  ├── YES → HTTP/Protobuf 사용
  │         (gRPC는 브라우저/Lambda에서 지원 불가)
  │
  └── NO ──▶ Q2. 방화벽이 HTTP/2 또는 gRPC를 차단하는가?
                ├── YES → HTTP/Protobuf 사용
                │         (HTTP/1.1로 폴백 가능)
                │
                └── NO ──▶ Q3. 초당 10,000 spans 이상인가?
                              ├── YES → gRPC 사용
                              │         (HTTP/2 멀티플렉싱, 최고 성능)
                              │
                              └── NO ──▶ Q4. 디버깅이 주 목적인가?
                                            ├── YES → HTTP/JSON 사용
                                            │         (사람이 읽을 수 있음)
                                            │
                                            └── NO → HTTP/Protobuf 사용
                                                      (가장 범용적, 무난한 선택)

# 하이브리드 Receiver 설정 (gRPC + HTTP 동시 수신)
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        max_recv_msg_size_mib: 16
        keepalive:
          server_parameters:
            max_connection_idle: 60s
            time: 30s
            timeout: 10s
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins: ['*']
          allowed_headers: ['*']
# 서비스 유형별 권장 구성
# ┌─────────────────────────┬──────────────────────────┐
# │ 서비스 유형              │ 권장 전송 방식             │
# ├─────────────────────────┼──────────────────────────┤
# │ 백엔드 (Java, Go)       │ gRPC (포트 4317)          │
# │ 프론트엔드 (Browser JS) │ HTTP/Protobuf (포트 4318) │
# │ 서버리스 (Lambda)       │ HTTP/Protobuf (포트 4318) │
# │ 디버깅/테스트           │ HTTP/JSON (포트 4318)     │
# │ IoT/Edge                │ HTTP/Protobuf (포트 4318) │
# └─────────────────────────┴──────────────────────────┘

OTel Collector 배포 패턴 비교
============================================

Pattern 1: Agent (DaemonSet)
  ┌─────────────────────────────────┐
  │          Kubernetes Node        │
  │  ┌─────────┐  ┌─────────┐      │
  │  │Service A│  │Service B│      │
  │  └────┬────┘  └────┬────┘      │
  │       │ localhost   │          │
  │       ▼             ▼          │
  │  ┌──────────────────────┐      │
  │  │   OTel Collector     │      │
  │  │   (DaemonSet Pod)    │      │
  │  └──────────┬───────────┘      │
  └─────────────┼──────────────────┘
                ▼
          ┌──────────┐
          │ Backend  │
          └──────────┘

Pattern 2: Sidecar
  ┌──────────────────────────────┐
  │      Application Pod         │
  │  ┌──────────┐ ┌───────────┐  │
  │  │App       │ │OTel       │  │
  │  │Container │→│Collector  │  │
  │  │          │ │(Sidecar)  │  │
  │  └──────────┘ └─────┬─────┘  │
  └─────────────────────┼────────┘
                        ▼
                  ┌──────────┐
                  │ Backend  │
                  └──────────┘

Pattern 3: Gateway (Deployment)
  [Service A]  [Service B]  [Service C]
       │            │            │
       └────────────┼────────────┘
                    ▼
          ┌──────────────────┐
          │  OTel Collector  │
          │  (Deployment,    │
          │   replicas: 3+)  │
          │  + HPA           │
          └────────┬─────────┘
                   ▼
             ┌──────────┐
             │ Backend  │
             └──────────┘

# otel-collector-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: otel-collector-agent
  namespace: observability
  labels:
    app: otel-collector
    component: agent
spec:
  selector:
    matchLabels:
      app: otel-collector
      component: agent
  template:
    metadata:
      labels:
        app: otel-collector
        component: agent
    spec:
      serviceAccountName: otel-collector
      containers:
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:0.120.0
          args:
            - '--config=/conf/otel-collector-config.yaml'
          ports:
            - containerPort: 4317 # gRPC
              hostPort: 4317
              protocol: TCP
            - containerPort: 4318 # HTTP
              hostPort: 4318
              protocol: TCP
            - containerPort: 8888 # Prometheus metrics
              protocol: TCP
          env:
            - name: K8S_NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: K8S_POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            - name: GOMEMLIMIT
              value: '460MiB' # Go runtime 메모리 제한
          resources:
            requests:
              cpu: 200m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 512Mi
          volumeMounts:
            - name: config
              mountPath: /conf
          livenessProbe:
            httpGet:
              path: /
              port: 13133 # health_check extension
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /
              port: 13133
            initialDelaySeconds: 5
            periodSeconds: 5
      volumes:
        - name: config
          configMap:
            name: otel-agent-config

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: otel-agent-config
  namespace: observability
data:
  otel-collector-config.yaml: |
    extensions:
      health_check:
        endpoint: 0.0.0.0:13133

    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318

      # 노드 레벨 메트릭 수집 (호스트 메트릭)
      hostmetrics:
        collection_interval: 30s
        scrapers:
          cpu: {}
          memory: {}
          disk: {}
          network: {}

      # Kubelet 메트릭 수집
      kubeletstats:
        collection_interval: 30s
        auth_type: "serviceAccount"
        endpoint: "https://${K8S_NODE_NAME}:10250"
        insecure_skip_verify: true

    processors:
      memory_limiter:
        check_interval: 1s
        limit_mib: 400
        spike_limit_mib: 100

      batch:
        send_batch_size: 1024
        timeout: 5s

      resource:
        attributes:
          - key: k8s.node.name
            value: "${K8S_NODE_NAME}"
            action: upsert

      # Kubernetes 메타데이터 자동 추가
      k8sattributes:
        auth_type: "serviceAccount"
        extract:
          metadata:
            - k8s.pod.name
            - k8s.pod.uid
            - k8s.namespace.name
            - k8s.deployment.name
            - k8s.node.name
          labels:
            - tag_name: app.label.team
              key: team
              from: pod
          annotations:
            - tag_name: app.annotation.version
              key: app-version
              from: pod

    exporters:
      # Traces → Gateway (Tail Sampling을 위해)
      loadbalancing:
        protocol:
          otlp:
            tls:
              insecure: true
        resolver:
          dns:
            hostname: otel-gateway-headless.observability.svc.cluster.local
            port: 4317

      # Metrics → Prometheus/Mimir 직접 전송
      prometheusremotewrite:
        endpoint: http://mimir.observability.svc.cluster.local:9009/api/v1/push

      # Logs → Loki 직접 전송
      otlp/logs:
        endpoint: loki.observability.svc.cluster.local:4317
        tls:
          insecure: true

    service:
      extensions: [health_check]
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, k8sattributes, resource, batch]
          exporters: [loadbalancing]
        metrics:
          receivers: [otlp, hostmetrics, kubeletstats]
          processors: [memory_limiter, k8sattributes, resource, batch]
          exporters: [prometheusremotewrite]
        logs:
          receivers: [otlp]
          processors: [memory_limiter, k8sattributes, resource, batch]
          exporters: [otlp/logs]

# otel-collector-gateway.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector-gateway
  namespace: observability
spec:
  replicas: 3
  selector:
    matchLabels:
      app: otel-collector
      component: gateway
  template:
    metadata:
      labels:
        app: otel-collector
        component: gateway
    spec:
      containers:
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:0.120.0
          args:
            - '--config=/conf/otel-collector-config.yaml'
          ports:
            - containerPort: 4317
              protocol: TCP
          env:
            - name: GOMEMLIMIT
              value: '3600MiB'
          resources:
            requests:
              cpu: 1000m
              memory: 2Gi
            limits:
              cpu: 4000m
              memory: 4Gi
          volumeMounts:
            - name: config
              mountPath: /conf
      volumes:
        - name: config
          configMap:
            name: otel-gateway-config

---
# Headless Service (Load Balancing Exporter의 DNS 리졸버용)
apiVersion: v1
kind: Service
metadata:
  name: otel-gateway-headless
  namespace: observability
spec:
  clusterIP: None
  selector:
    app: otel-collector
    component: gateway
  ports:
    - port: 4317
      targetPort: 4317
      protocol: TCP

---
# HPA (수평 자동 확장)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: otel-gateway-hpa
  namespace: observability
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: otel-collector-gateway
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 75

# OpenTelemetryCollector CRD를 통한 선언적 배포
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel-agent
  namespace: observability
spec:
  mode: daemonset # daemonset | deployment | sidecar | statefulset
  image: otel/opentelemetry-collector-contrib:0.120.0
  resources:
    requests:
      cpu: 200m
      memory: 256Mi
    limits:
      cpu: 1000m
      memory: 512Mi
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      memory_limiter:
        check_interval: 1s
        limit_mib: 400
      batch:
        send_batch_size: 1024
        timeout: 5s
    exporters:
      otlp:
        endpoint: otel-gateway.observability.svc.cluster.local:4317
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [otlp]

---
# 자동 계측 주입 (Java 애플리케이션에 OTel Agent 자동 설치)
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: java-instrumentation
  namespace: production
spec:
  exporter:
    endpoint: http://otel-agent.observability.svc.cluster.local:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: '0.25' # Head-based 25% (Tail sampling이 추가 필터링)
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
    env:
      - name: OTEL_JAVAAGENT_DEBUG
        value: 'false'

---
# 이 annotation을 Pod/Deployment에 추가하면 자동 계측 활성화
# metadata:
#   annotations:
#     instrumentation.opentelemetry.io/inject-java: "java-instrumentation"

체크리스트
============================================
[ ] OTel Collector를 Kubernetes DaemonSet으로 배포
[ ] OTLP Receiver (gRPC + HTTP) 활성화
[ ] 백엔드 선택 및 Exporter 설정 (Tempo, Jaeger 등)
[ ] memory_limiter 프로세서 설정
[ ] health_check extension 설정
[ ] Collector 자체 메트릭 모니터링 (Prometheus scrape)
[ ] 파일럿 서비스 1~2개에 자동 계측 적용
[ ] 기본 대시보드 구축 (RED metrics: Rate, Errors, Duration)

체크리스트
============================================
[ ] Semantic Conventions 가이드 작성 및 팀 교육
[ ] 레거시 속성명 정규화를 위한 attributes 프로세서 설정
[ ] 자동 계측을 전체 서비스로 확산
[ ] k8sattributes 프로세서로 Kubernetes 메타데이터 자동 부착
[ ] resource 프로세서로 필수 리소스 속성 보장
[ ] service.name, deployment.environment 등 필수 속성 검증
[ ] 알림 규칙 설정 (에러율, 지연 시간 임계치)

체크리스트
============================================
[ ] 비즈니스 크리티컬 로직에 수동 계측 추가 (하이브리드 전략)
[ ] W3C Baggage를 통한 비즈니스 컨텍스트 전파 도입
[ ] Tail-based sampling을 위한 2-tier Collector 아키텍처 구축
[ ] Load Balancing Exporter 설정 (Trace ID 기반)
[ ] tail_sampling 프로세서 정책 설계 및 튜닝
[ ] Cross-signal correlation 대시보드 구축
[ ] SLO(Service Level Objective) 기반 모니터링

체크리스트
============================================
[ ] 샘플링 정책 지속적 튜닝 (비용 vs 가시성 최적화)
[ ] Collector 리소스 사용량 모니터링 및 자동 확장(HPA) 적용
[ ] OTel Operator 도입 (자동 계측 주입 자동화)
[ ] 멀티 클러스터 / 멀티 리전 옵저버빌리티 통합
[ ] Baggage 보안 정책 (Trust Boundary 필터링)
[ ] 팀별 셀프 서비스 대시보드 가이드라인
[ ] 정기적인 옵저버빌리티 성숙도 평가

# production-otel-collector.yaml
# 프로덕션 레벨의 완전한 Collector 파이프라인

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777 # Go pprof 프로파일링
  zpages:
    endpoint: 0.0.0.0:55679 # 디버깅용 zPages

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        max_recv_msg_size_mib: 16
      http:
        endpoint: 0.0.0.0:4318

  # Prometheus 메트릭 스크래핑 (기존 Prometheus 타겟 호환)
  prometheus:
    config:
      scrape_configs:
        - job_name: 'kubernetes-pods'
          kubernetes_sd_configs:
            - role: pod
          relabel_configs:
            - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
              action: keep
              regex: true

  # 호스트 메트릭
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      disk: {}
      network: {}

processors:
  # 1. 메모리 보호 (항상 첫 번째)
  memory_limiter:
    check_interval: 1s
    limit_mib: 1800
    spike_limit_mib: 400

  # 2. Kubernetes 메타데이터 부착
  k8sattributes:
    auth_type: 'serviceAccount'
    passthrough: false
    extract:
      metadata:
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.namespace.name
        - k8s.deployment.name
        - k8s.statefulset.name
        - k8s.daemonset.name
        - k8s.node.name
      labels:
        - tag_name: service.team
          key: team
          from: pod
        - tag_name: service.component
          key: component
          from: pod

  # 3. 리소스 속성 보장
  resource:
    attributes:
      - key: deployment.environment.name
        value: 'production'
        action: insert
      - key: service.namespace
        value: 'default'
        action: insert

  # 4. 속성 정규화 (Semantic Conventions)
  attributes/normalize:
    actions:
      - key: http.request.method
        action: upsert
        from_attribute: http.method
      - key: http.response.status_code
        action: upsert
        from_attribute: http.status_code

  # 5. 민감 정보 제거
  attributes/redact:
    actions:
      - key: db.query.text
        action: hash # 쿼리를 해시로 대체
      - key: http.request.header.authorization
        action: delete
      - key: http.request.header.cookie
        action: delete

  # 6. 불필요한 Span 필터링
  filter/drop-health:
    error_mode: ignore
    traces:
      span:
        - 'attributes["http.target"] == "/health"'
        - 'attributes["http.target"] == "/readyz"'
        - 'attributes["http.target"] == "/livez"'
        - 'attributes["http.route"] == "/metrics"'

  # 7. 배치 처리
  batch:
    send_batch_size: 2048
    send_batch_max_size: 4096
    timeout: 10s

exporters:
  # Traces → Grafana Tempo
  otlp/tempo:
    endpoint: tempo.observability.svc.cluster.local:4317
    tls:
      insecure: true
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
    sending_queue:
      enabled: true
      num_consumers: 10
      queue_size: 5000

  # Metrics → Prometheus Remote Write (Mimir)
  prometheusremotewrite:
    endpoint: http://mimir.observability.svc.cluster.local:9009/api/v1/push
    tls:
      insecure: true
    retry_on_failure:
      enabled: true

  # Logs → Grafana Loki
  otlp/loki:
    endpoint: loki.observability.svc.cluster.local:4317
    tls:
      insecure: true

  # 디버깅용 (개발 환경에서만 활성화)
  debug:
    verbosity: basic
    sampling_initial: 5
    sampling_thereafter: 200

service:
  extensions: [health_check, pprof, zpages]

  telemetry:
    metrics:
      address: 0.0.0.0:8888
      level: detailed
    logs:
      level: info
      encoding: json

  pipelines:
    traces:
      receivers: [otlp]
      processors:
        - memory_limiter
        - k8sattributes
        - resource
        - attributes/normalize
        - attributes/redact
        - filter/drop-health
        - batch
      exporters: [otlp/tempo]

    metrics:
      receivers: [otlp, prometheus, hostmetrics]
      processors:
        - memory_limiter
        - k8sattributes
        - resource
        - batch
      exporters: [prometheusremotewrite]

    logs:
      receivers: [otlp]
      processors:
        - memory_limiter
        - k8sattributes
        - resource
        - attributes/redact
        - batch
      exporters: [otlp/loki]