Loki - Tempo 연동(w. opentelemetry)

🧭 사용법 요약 (공식 문서 기준)

✅ 기본 구성 요소

1. Ingress NGINX – OpenTelemetry 모듈 활성화
2. OpenTelemetry Collector – OTLP gRPC 포트 수신 (4317)
3. Trace Backend (e.g., Tempo) – Collector에서 데이터 수신

---

🛠️ 1. NGINX 설정: Tracing 활성화

Helm 설치 시 tracing 활성화 옵션을 추가합니다:

helm upgrade --install ingress-nginx ingress-nginx \\
  --repo <https://kubernetes.github.io/ingress-nginx> \\
  --namespace ingress-nginx --create-namespace \\
  --set controller.opentelemetry.enabled=true \\
  --set controller.opentelemetry.endpoint="otel-collector:4317" \\
  --set controller.opentelemetry.sampler="always_on" \\
  --set controller.opentelemetry.serviceName="ingress-nginx"

🔹 otel-collector:4317 은 OTLP gRPC 포트를 사용하는 OpenTelemetry Collector 서비스 주소입니다.

---

⚙️ 2. OpenTelemetry Collector 구성 (필수)

Collector가 OTLP 데이터를 수신하고, Tempo로 전송합니다. 예시:

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  otlp/tempo:
    endpoint: tempo.monitoring.svc.cluster.local:4317
    tls:
      insecure: true
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/tempo, logging]

Collector는 otel-collector 라는 이름으로 서비스되어야 위 Helm 설정과 연결됩니다.

---

🔗 3. 전체 데이터 흐름

[App / Ingress]
      ↓
[OpenTelemetry Collector]
      ↓
  OTLP/gRPC Exporter
      ↓
[Tempo]
      ↓
[Grafana Tempo Plugin]

• Ingress NGINX가 traceparent 헤더로 요청마다 trace를 생성
• 이 trace는 OTLP gRPC로 Collector에 전송됨
• Collector는 이를 Tempo에 저장
• Grafana에서 Tempo를 데이터 소스로 추가하여 시각화 가능

---

📋 주요 Helm 옵션 정리

옵션 설명

controller.opentelemetry.enabled	OpenTelemetry tracing 활성화
controller.opentelemetry.endpoint	OTLP gRPC 수신 주소 (Collector)
controller.opentelemetry.sampler	샘플링 전략 (always_on, always_off, traceidratio)
controller.opentelemetry.serviceName	trace에 표시될 서비스 이름 (예: ingress-nginx)

---

🎯 로그에서 traceID 추적

Ingress NGINX는 자동으로 traceparent 헤더를 백엔드로 전달하므로, Flask 등 앱에서 이를 추출해 로그에 출력하면 Loki → Tempo 연동이 가능해집니다.

---

Loki - Tempo 연동

Grafana UI에서:

⚙️ Configuration → Data Sources → Loki → Trace → Derived fields

---

✅ 예시 설정

🔹 Name

• TraceID: 이 필드는 Grafana Explore 탭에서 표시될 이름입니다.
• 로그 라인에서 추출된 trace_id 옆에 TraceID로 보입니다.

---

🔹 Type

• Regex in log line: 로그 라인에서 정규표현식으로 값을 추출하겠다는 의미입니다.

---

🔹 Regex

• trace_id=(\\w+)
  • 로그 메시지에서 trace_id=abc123... 와 같은 형태를 찾아 abc123만 추출합니다.
  • \\w+는 알파벳+숫자+언더스코어 ([a-zA-Z0-9_]) 한 개 이상을 의미합니다.

예시 로그:

level=info msg="something" trace_id=abcd1234efgh5678

→ 위 로그에서 abcd1234efgh5678이 추출됩니다.

---

🔹 Query

• v1/traces/${__value.raw}
  • 추출한 trace_id를 Tempo의 trace API 경로로 사용합니다.
  • 이 URL은 내부적으로 Tempo datasource와 연결되어 사용됩니다.
  • ${__value.raw}는 Regex에서 추출한 값입니다.

---

🔹 Internal link

• 활성화되어 있음 (tempo 선택됨):
  • 이 옵션은 Grafana가 이 값을 Tempo datasource로 직접 연결해주는 것을 의미합니다.
  • 클릭하면 Tempo에서 해당 trace를 바로 확인할 수 있는 UI로 이동합니다.

---

✅ 작동 방식 요약

1. Loki 로그에서 trace_id=abc123... 형식을 찾음
2. 정규식 trace_id=(\\w+)에 의해 abc123을 추출
3. URL 템플릿 v1/traces/${__value.raw}로 변환 → v1/traces/abc123
4. Grafana가 연결된 tempo 데이터소스를 사용해 Tempo UI에서 해당 trace 조회

---

✅ 잘 동작하는지 확인하려면?

1. 로그에 trace_id=... 문자열이 포함되어 있어야 합니다.
2. Explore → Loki에서 해당 로그를 조회해보세요.
3. 로그 오른쪽에 🔗 TraceID 링크가 생성되어야 합니다.
4. 클릭 시 Tempo trace 뷰로 이동해야 합니다.

✅ 참고 팁

• 로그가 JSON 형태일 경우:
• Regex를 "trace_id":"([^"]+)" 식으로 수정해야 할 수 있습니다.