Registry /
observability / opentelemetry-instrumentation-flask
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.000s · 52.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 0.000s · 51MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlaskInstrumentor
✓ from opentelemetry.instrumentation.flask import FlaskInstrumentor
This quickstart demonstrates how to instrument a basic Flask application using `FlaskInstrumentor`. It sets up a `TracerProvider` with a `BatchSpanProcessor` and `OTLPSpanExporter` to send traces. Run this script, then access `http://localhost:5000/` or `http://localhost:5000/data` to generate traces. Ensure an OpenTelemetry Collector is running and configured to receive OTLP/HTTP traces at the specified endpoint.
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 BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
# Configure OpenTelemetry SDK
# Ensure these environment variables are set for your OTLP collector
otlp_endpoint = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4318/v1/traces')
service_name = os.environ.get('OTEL_SERVICE_NAME', 'my-flask-app')
resource = Resource.create({
"service.name": service_name,
"service.version": "1.0.0"
})
provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=otlp_endpoint))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
app = Flask(__name__)
# Instrument the Flask application
FlaskInstrumentor().instrument_app(app)
@app.route("/")
def hello():
return "Hello, World!"
@app.route("/data")
def get_data():
# Example of manual span within an instrumented route
with trace.get_current_span().tracer.start_as_current_span("get-data-logic"):
return {"value": 123}
if __name__ == "__main__":
# IMPORTANT: Do not run with debug=True in production or with auto-instrumentation
# due to Flask reloader issues with OpenTelemetry. For development, use
# `flask run --no-debugger --no-reloader` or set `debug=False` for basic testing.
print(f"Flask app running on http://127.0.0.1:5000 with OTLP exporter to {otlp_endpoint}")
app.run(host="0.0.0.0", port=5000, debug=False)
Debug
Known issues
breakingThis instrumentation package is currently in beta (`0.x.x`), indicating that its API and behavior may change in future releases without strictly adhering to semantic versioning until a stable `1.0` release.fixReview changelogs carefully when upgrading. Be prepared for potential API changes and adjust your code accordingly.
affects: All `0.x.x` beta versions
gotchaFlask's debug mode, which uses a reloader, can conflict with OpenTelemetry's instrumentation process, leading to duplicate spans or no instrumentation. This often occurs when `app.run(debug=True)` is used directly.fixFor development with tracing, run Flask using `flask run --no-debugger --no-reloader` or explicitly set `debug=False` in `app.run()`. In production, use WSGI servers like Gunicorn or uWSGI, which typically don't use the reloader.
affects: All versions when using Flask's reloader/debug mode.
gotchaWhen manually instrumenting, `FlaskInstrumentor().instrument_app(app)` must be called *after* the Flask application object (`app`) has been created and typically after configuring all blueprints, but *before* the application starts serving requests. Also, the global `TracerProvider` must be set up *before* instrumentation is applied.fixEnsure `trace.set_tracer_provider(provider)` is called early in your application's lifecycle, and `FlaskInstrumentor().instrument_app(app)` is called after your `app` is initialized and configured but before `app.run()` or a WSGI server takes over.
affects: All versions.
gotchaWhen using `opentelemetry-instrument` CLI for auto-instrumentation, Flask's development server with the reloader enabled (`--debug` or `FLASK_DEBUG=1`) is not supported and will lead to broken instrumentation. The CLI relies on patching modules once.fixRun your Flask application without the reloader when using `opentelemetry-instrument`, e.g., `opentelemetry-instrument flask run --no-debugger --no-reloader`.
affects: All versions when using `opentelemetry-instrument` with Flask's reloader.
deprecatedOlder versions of Flask instrumentation (`<0.45b0`) did not include the HTTP method in the span name. This was changed to `HTTP {method} {route}` for better semantic convention compliance.fixUpgrade to `opentelemetry-instrumentation-flask` version `0.45b0` or newer to align with updated semantic conventions. Be aware of potential changes in how your observability backend groups or displays traces if you were relying on the older span naming.
affects: <0.45b0
breakingThe `flask` package, which is a required dependency, is not installed. This prevents `opentelemetry-instrumentation-flask` from being used as it cannot find the Flask application to instrument.fixEnsure that `flask` is installed in your environment, typically via `pip install flask`.
affects: All versions.
gotchaThe `opentelemetry-instrumentation-flask` library requires the `flask` package to be installed in your environment. Failure to install Flask will result in a `ModuleNotFoundError` when attempting to import Flask components.fixEnsure `flask` is included in your project's dependencies and installed (e.g., `pip install flask`).
affects: All versions.
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
FlaskrequiredThe web framework being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry data.