OpenTelemetry Flask Instrumentation

Warnings

• breaking This 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.
  Fix: Review changelogs carefully when upgrading. Be prepared for potential API changes and adjust your code accordingly.
• gotcha Flask'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.
  Fix: For 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.
• gotcha When 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.
  Fix: Ensure `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.
• gotcha When 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.
  Fix: Run your Flask application without the reloader when using `opentelemetry-instrument`, e.g., `opentelemetry-instrument flask run --no-debugger --no-reloader`.
• deprecated Older 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.
  Fix: Upgrade 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.

Install

• pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-flask opentelemetry-exporter-otlp Install core, SDK, Flask instrumentation, and OTLP exporter

Imports

• FlaskInstrumentor

  from opentelemetry.instrumentation.flask import FlaskInstrumentor

Quickstart

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)