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.13.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.13.0-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: spakky_opentelemetry-6.13.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.13.0.tar.gz
Algorithm Hash digest
SHA256 6ca4b346a503e490f89e7e92ebe2b078c4912d3045158242226ff71d0ebaae91
MD5 79af9362802c607cf65e09024de6f782
BLAKE2b-256 952fcb4a49b32d596160304e619c5de2f6bbba3a56da2815d14b7b63dbb177e8

See more details on using hashes here.

Provenance

The following attestation bundles were made for spakky_opentelemetry-6.13.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.13.0-py3-none-any.whl.

File metadata

File hashes

Hashes for spakky_opentelemetry-6.13.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b5eb40000938ea6ed4ada76acccfc2c621a57057f04077170912779b6e5b2d3c
MD5 5c6776bcb707f7bd25ad5c5904757637
BLAKE2b-256 b167fb27ea55f7c51dd1cb47abf39acbe2568018729a38d3caaafdb07fbb9225

See more details on using hashes here.

Provenance

The following attestation bundles were made for spakky_opentelemetry-6.13.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