{"id":9163,"library":"otel-extensions","title":"OpenTelemetry Python Extensions","description":"OpenTelemetry Extensions for Python is a collection of helper classes, functions, and decorators designed to simplify the use of the OpenTelemetry Python API and SDK packages. It currently supports Python >= 3.8 and is actively maintained, with version 1.1.0 released in October 2024.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/s4v4g3/otel-extensions-python","tags":["OpenTelemetry","Observability","Tracing","Metrics","Logging","Instrumentation","Distributed Tracing","Python"],"install":[{"cmd":"pip install otel-extensions","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core OpenTelemetry API, essential for creating telemetry data.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK, providing implementations for the API.","package":"opentelemetry-sdk","optional":false},{"reason":"Specific SDK extension for AWS integration, required by some features.","package":"opentelemetry-sdk-extension-aws","optional":false},{"reason":"Used for exporting telemetry data via OTLP (OpenTelemetry Protocol).","package":"opentelemetry-exporter-otlp","optional":false}],"imports":[{"note":"Initializes the global OpenTelemetry tracer provider.","symbol":"init_telemetry_provider","correct":"from otel_extensions import init_telemetry_provider"},{"note":"Configuration options for the telemetry provider.","symbol":"TelemetryOptions","correct":"from otel_extensions import TelemetryOptions"},{"note":"Decorator to automatically wrap a span around a function or method.","symbol":"@instrumented","correct":"from otel_extensions import instrumented"},{"note":"Helper class for propagating trace context across threads or processes.","symbol":"TraceContextCarrier","correct":"from otel_extensions import TraceContextCarrier"},{"note":"A logging.Handler that creates events for log messages within a span.","symbol":"TraceEventLogHandler","correct":"from otel_extensions import TraceEventLogHandler"}],"quickstart":{"code":"import os\nfrom otel_extensions import init_telemetry_provider, TelemetryOptions\nfrom opentelemetry import trace\n\n# Configure telemetry options, can also be set via environment variables\noptions = TelemetryOptions(\n    OTEL_EXPORTER_OTLP_ENDPOINT=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4317/'),\n    OTEL_EXPORTER_OTLP_PROTOCOL=os.environ.get('OTEL_EXPORTER_OTLP_PROTOCOL', 'grpc'),\n    OTEL_SERVICE_NAME=os.environ.get('OTEL_SERVICE_NAME', 'my-service'),\n    OTEL_PROCESSOR_TYPE=os.environ.get('OTEL_PROCESSOR_TYPE', 'batch')\n)\n\n# Initialize the global tracer provider\ninit_telemetry_provider(options)\n\n# Get a tracer and create a span\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"example-operation\") as span:\n    span.set_attribute(\"custom.attribute\", \"example_value\")\n    print(\"Performing an example operation with tracing...\")\n\nprint(\"Telemetry provider initialized and example span created.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment is 3.8 or newer. OpenTelemetry Python officially supports 3.9 and higher for latest releases.","message":"The `otel-extensions` library (and core OpenTelemetry Python) requires Python >= 3.8. Using older Python versions may lead to unexpected behavior or lack of support.","severity":"gotcha","affected_versions":"< 1.0.0 (for otel-extensions itself, but for OTel Python ecosystem generally affects < 3.8)"},{"fix":"Monitor 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.","message":"OpenTelemetry 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.","severity":"breaking","affected_versions":"All versions that integrate with OpenTelemetry Python SDK, especially during transitions to new semantic conventions (e.g., opentelemetry-python-contrib versions >= 1.40.0)."},{"fix":"Migrate from Jaeger exporters to OTLP (OpenTelemetry Protocol) for exporting traces to Jaeger or other compatible backends. OTLP is the recommended and stable export mechanism.","message":"Jaeger 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.","severity":"deprecated","affected_versions":"OpenTelemetry Python SDK versions >= 1.16.0/0.37b0 (approx. Feb 2023)."},{"fix":"Exercise 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.","message":"Many 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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install otel-extensions` to install the library.","cause":"The `otel-extensions` package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'otel_extensions'"},{"fix":"Verify 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.","cause":"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.","error":"Telemetry data is not appearing in my backend (e.g., Jaeger, Prometheus, OTLP Collector)."},{"fix":"Use the `TraceContextCarrier` class provided by `otel-extensions` to capture and attach trace context when spawning new threads or processes.","cause":"Python's threading and multiprocessing models often require explicit context management for OpenTelemetry traces.","error":"Trace context is not propagated across threads or processes."},{"fix":"Ensure `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.","cause":"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.","error":"Instrumentation decorator (`@instrumented`) is not creating spans."}]}