spakky-opentelemetry 6.9.0

OpenTelemetry SDK bridge for Spakky Framework

spakky-opentelemetry

Spakky Framework를 OpenTelemetry SDK에 연결하는 observability bridge입니다. spakky-tracing의 W3C propagator를 OpenTelemetry propagator로 교체하고, 선택적으로 logging context와 trace context를 동기화합니다.

spakky-tracing이 제공하는 ITracePropagator 인터페이스의 OpenTelemetry 구현체입니다. 플러그인을 설치하면 OTelSetupPostProcessor가 컨테이너의 W3CTracePropagator를 OTelTracePropagator로 자동 교체하여, OTel 백엔드(Jaeger, Grafana Tempo 등)와 연동합니다.

spakky-tracing과의 관계

spakky-tracing은 TraceContext와 ITracePropagator 추상화를 제공하고, 기본 구현체로 W3CTracePropagator를 등록합니다. spakky-opentelemetry는 이 기본 구현체를 런타임에 교체합니다:

1. OTelSetupPostProcessor(@Order(0))가 Pod 후처리 단계에서 W3CTracePropagator 인스턴스를 감지
2. 해당 인스턴스를 OTelTracePropagator로 교체하여 반환
3. 동시에 OTel TracerProvider를 설정 (exporter, sampler, resource)

따라서 spakky-tracing만 설치하면 순수 W3C TraceContext 전파가 동작하고, spakky-opentelemetry를 추가하면 OTel SDK 기반 전파로 업그레이드됩니다.

설치

pip install spakky-opentelemetry

spakky-logging 브릿지 사용 시:

pip install spakky-opentelemetry[logging]

주요 기능

컴포넌트	역할
OpenTelemetryConfig	@Configuration — 환경변수 기반 OTel SDK 설정
OTelSetupPostProcessor	IPostProcessor — TracerProvider 초기화 및 W3CTracePropagator 교체
OTelTracePropagator	ITracePropagator 구현 — OTel SDK의 TraceContextTextMapPropagator 브릿지
LogContextBridge	TraceContext의 trace_id/span_id를 spakky-logging의 LogContext에 동기화 (선택)
ExporterType	StrEnum — 지원 exporter 타입 (otlp, console, none)

설정

환경변수로 설정합니다 (OpenTelemetryConfig, env prefix: SPAKKY_OTEL_):

환경변수	기본값	설명
SPAKKY_OTEL_SERVICE_NAME	spakky-service	OTel 서비스 이름
SPAKKY_OTEL_EXPORTER_TYPE	otlp	스팬 exporter (otlp, console, none)
SPAKKY_OTEL_EXPORTER_ENDPOINT	http://localhost:4317	OTLP collector 엔드포인트
SPAKKY_OTEL_SAMPLE_RATE	1.0	트레이스 샘플링 비율 (0.0~1.0)

사용법

플러그인은 spakky.plugins 엔트리 포인트로 자동 등록됩니다. SpakkyApplication.load_plugins()를 호출하면 자동으로 활성화됩니다.

from spakky.core.application.application import SpakkyApplication
from spakky.core.application.application_context import ApplicationContext

app = (
    SpakkyApplication(ApplicationContext())
    .load_plugins()  # spakky-opentelemetry 자동 로드
    .scan(my_module)
    .start()
)

LogContext 브릿지

spakky-logging이 설치되어 있으면 LogContextBridge pod instance의 sync()를 호출하여 trace_id/span_id를 로그 컨텍스트에 바인딩할 수 있습니다. spakky-logging이 없으면 no-op으로 동작합니다:

from spakky.plugins.opentelemetry.bridge import LogContextBridge

# TraceContext 설정 후
bridge = app.container.get(type_=LogContextBridge)
bridge.sync()  # LogContext에 trace_id, span_id 바인딩

라이선스

MIT License