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는 이 기본 구현체를 런타임에 교체합니다:

OTelSetupPostProcessor(@Order(0))가 Pod 후처리 단계에서 W3CTracePropagator 인스턴스를 감지
해당 인스턴스를 OTelTracePropagator로 교체하여 반환
동시에 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 바인딩

개발 검증

패키지 단위 검증은 해당 패키지 디렉토리에서 실행합니다.

uv run ruff format .
uv run ruff check .
uv run pyrefly check
uv run pytest

pytest는 각 패키지 pyproject.toml의 coverage 설정을 사용합니다.

라이선스

MIT License

Metadata

Release files for spakky-opentelemetry 8.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spakky-opentelemetry 8.1.0
File	Size	Uploaded
spakky_opentelemetry-8.1.0.tar.gz	6.5 kB	Aug 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spakky-opentelemetry 8.1.0
File	Interpreter	ABI	Platform	Reset
spakky_opentelemetry-8.1.0-py3-none-any.whl 9.2 kB Aug 22, 2026	Python 3	none	any	Details

Total release size: 15.7 kB

Release files / spakky_opentelemetry-8.1.0.tar.gz

Download URL	spakky_opentelemetry-8.1.0.tar.gz
Size	6.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`0b0c0e8aa57b65a2155f71eb6165a8dbc50233c238c55caa65149c5999945776`
BLAKE2b-256 checksum How to use checksums	`e4e1dc5d630d950fcba2ad544bede40aa771c1710a1b73a21642729398fddfda`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/E5presso/spakky-framework
Publishing commit: github.com/E5presso/spakky-framework/tree/e29216bdd41ad11f48d1f6147368d4b748fefadc

Workflow

Publishing configuration: github.com/E5presso/spakky-framework/blob/e29216bdd41ad11f48d1f6147368d4b748fefadc/.github/workflows/release.yml
Publishing logs: github.com/E5presso/spakky-framework/actions/runs/32573122611/attempts/1

Artifact

Subject: spakky_opentelemetry-8.1.0.tar.gz
SHA-256 checksum: 0b0c0e8aa57b65a2155f71eb6165a8dbc50233c238c55caa65149c5999945776 Verifying attestations

Release files / spakky_opentelemetry-8.1.0-py3-none-any.whl

Download URL	spakky_opentelemetry-8.1.0-py3-none-any.whl
Size	9.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ee4ad66b83e458c46b6ed18db545adc8f90f0c4c61addd7286a4681c0f517fac`
BLAKE2b-256 checksum How to use checksums	`e56a9e32d80d9b53c91c1729678b6284615facfcdf274abab1ad39738ef1b444`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/E5presso/spakky-framework
Publishing commit: github.com/E5presso/spakky-framework/tree/e29216bdd41ad11f48d1f6147368d4b748fefadc

Workflow

Publishing configuration: github.com/E5presso/spakky-framework/blob/e29216bdd41ad11f48d1f6147368d4b748fefadc/.github/workflows/release.yml
Publishing logs: github.com/E5presso/spakky-framework/actions/runs/32573122611/attempts/1

Artifact

Subject: spakky_opentelemetry-8.1.0-py3-none-any.whl
SHA-256 checksum: ee4ad66b83e458c46b6ed18db545adc8f90f0c4c61addd7286a4681c0f517fac Verifying attestations