Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.321s · 22.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.301s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
init_telemetry_provider
✓ from otel_extensions import init_telemetry_provider
Initializes the global OpenTelemetry tracer provider.
TelemetryOptions
✓ from otel_extensions import TelemetryOptions
Configuration options for the telemetry provider.
@instrumented
✓ from otel_extensions import instrumented
Decorator to automatically wrap a span around a function or method.
TraceContextCarrier
✓ from otel_extensions import TraceContextCarrier
Helper class for propagating trace context across threads or processes.
TraceEventLogHandler
✓ from otel_extensions import TraceEventLogHandler
A logging.Handler that creates events for log messages within a span.
This quickstart demonstrates how to initialize the OpenTelemetry tracer provider using `otel-extensions` and create a basic traced operation. It shows how to configure common options, which can also be provided via environment variables.
import os
from otel_extensions import init_telemetry_provider, TelemetryOptions
from opentelemetry import trace
# Configure telemetry options, can also be set via environment variables
options = TelemetryOptions(
OTEL_EXPORTER_OTLP_ENDPOINT=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4317/'),
OTEL_EXPORTER_OTLP_PROTOCOL=os.environ.get('OTEL_EXPORTER_OTLP_PROTOCOL', 'grpc'),
OTEL_SERVICE_NAME=os.environ.get('OTEL_SERVICE_NAME', 'my-service'),
OTEL_PROCESSOR_TYPE=os.environ.get('OTEL_PROCESSOR_TYPE', 'batch')
)
# Initialize the global tracer provider
init_telemetry_provider(options)
# Get a tracer and create a span
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("example-operation") as span:
span.set_attribute("custom.attribute", "example_value")
print("Performing an example operation with tracing...")
print("Telemetry provider initialized and example span created.")
Debug
Known issues
gotchaThe `otel-extensions` library (and core OpenTelemetry Python) requires Python >= 3.8. Using older Python versions may lead to unexpected behavior or lack of support.fixEnsure your Python environment is 3.8 or newer. OpenTelemetry Python officially supports 3.9 and higher for latest releases.
affects: < 1.0.0 (for otel-extensions itself, but for OTel Python ecosystem generally affects < 3.8)
breakingOpenTelemetry Python is undergoing a migration to stable semantic conventions, particularly for HTTP-related instrumentations. This could change attribute names or data structures, requiring updates to consuming systems or custom code that relies on specific semantic attributes.fixMonitor OpenTelemetry Python changelogs (especially for `opentelemetry-python-contrib`) for semantic convention updates and adjust your code/configurations accordingly. Refer to the official OpenTelemetry semantic conventions documentation.
affects: All versions that integrate with OpenTelemetry Python SDK, especially during transitions to new semantic conventions (e.g., opentelemetry-python-contrib versions >= 1.40.0).
deprecatedJaeger exporters have been deprecated in the core OpenTelemetry Python SDK. If `otel-extensions` previously provided helpers for Jaeger, these might become non-functional or removed in future versions.fixMigrate from Jaeger exporters to OTLP (OpenTelemetry Protocol) for exporting traces to Jaeger or other compatible backends. OTLP is the recommended and stable export mechanism.
affects: OpenTelemetry Python SDK versions >= 1.16.0/0.37b0 (approx. Feb 2023).
gotchaMany instrumentation packages within the `opentelemetry-python-contrib` repository, which `otel-extensions` may implicitly rely on or complement, are still in 'beta' status. They are generally not recommended for production environments without thorough testing.fixExercise caution when deploying systems heavily reliant on `opentelemetry-python-contrib` packages in production. Regularly review their stability status and contribute to their stabilization if possible.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'otel_extensions'
The `otel-extensions` package has not been installed in the current Python environment.
fixRun `pip install otel-extensions` to install the library.
Telemetry data is not appearing in my backend (e.g., Jaeger, Prometheus, OTLP Collector).
This is typically caused by incorrect configuration of the exporter endpoint, service name, or processor type, or the OpenTelemetry Collector/backend not running or being inaccessible.
fixVerify that `OTEL_EXPORTER_OTLP_ENDPOINT` (or equivalent for other exporters) is correctly set to your collector/backend address and port (e.g., `http://localhost:4317/`). Ensure `OTEL_SERVICE_NAME` is set for proper identification. Check that the OpenTelemetry Collector or your chosen backend is running and reachable. Also, confirm that `init_telemetry_provider()` is called early in your application's lifecycle.
Trace context is not propagated across threads or processes.
Python's threading and multiprocessing models often require explicit context management for OpenTelemetry traces.
fixUse the `TraceContextCarrier` class provided by `otel-extensions` to capture and attach trace context when spawning new threads or processes.
Instrumentation decorator (`@instrumented`) is not creating spans.
This can happen if the global tracer provider is not initialized before the decorated function is called, or if environment variables like `OTEL_PROCESS_MODULES` are restricting instrumentation.
fixEnsure `init_telemetry_provider()` is called at the very beginning of your application. Check if `OTEL_PROCESS_MODULES` environment variable is set and if the module containing the decorated function is included in its list, if applicable.
Upgrade
Version history
1.1.0latest on PyPI · released Oct 21, 2024
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API, essential for creating telemetry data.
opentelemetry-sdkrequiredCore OpenTelemetry SDK, providing implementations for the API.
opentelemetry-sdk-extension-awsrequiredSpecific SDK extension for AWS integration, required by some features.
opentelemetry-exporter-otlprequiredUsed for exporting telemetry data via OTLP (OpenTelemetry Protocol).