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 바인딩

개발 검증

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

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

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

라이선스

MIT License

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (8.0.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Spakky from gravatar.com Spakky

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Spakky

License

MIT

Requires

Python >=3.12

Provides Extra

logging otlp

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spakky_opentelemetry-6.11.0.tar.gz (6.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

spakky_opentelemetry-6.11.0-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

Details for the file spakky_opentelemetry-6.11.0.tar.gz.

File metadata

  • Download URL: spakky_opentelemetry-6.11.0.tar.gz
  • Upload date:
  • Size: 6.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for spakky_opentelemetry-6.11.0.tar.gz
Algorithm Hash digest
SHA256 c3a09cd9eb682d5a92e23b7a887eb33bc28d827aef99328c5813bd3595f4ddc3
MD5 ef20cafbf4209923b9306f0785c0207f
BLAKE2b-256 658468e588893933440bd6da0d89a1ea8fcf9f90db77184df80cdbd2d4482e95

See more details on using hashes here.

Provenance

The following attestation bundles were made for spakky_opentelemetry-6.11.0.tar.gz:

Publisher: release.yml on E5presso/spakky-framework

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file spakky_opentelemetry-6.11.0-py3-none-any.whl.

File metadata

File hashes

Hashes for spakky_opentelemetry-6.11.0-py3-none-any.whl
Algorithm Hash digest
SHA256 46720e9ed1aba0afb463f3b915d411ecc4f4bf2d61bc585057a3bd5d6dd8f8af
MD5 4d96f96e955ddfc50946dbc1bca685ce
BLAKE2b-256 64c9bb553f0caf0346df6ebfa3e932a49a4bfe1a8e939a5602f27256c250b4cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for spakky_opentelemetry-6.11.0-py3-none-any.whl:

Publisher: release.yml on E5presso/spakky-framework

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page