Flask OpenTracing

Common errors

• TypeError: __init__() missing 1 required positional argument: 'tracer'

  cause Attempting to initialize `FlaskTracing` without providing an `opentracing.Tracer` instance as the first argument, which became mandatory in v1.0.0+.
  fix Initialize `FlaskTracing` with a tracer object: `FlaskTracing(MockTracer(), app=app)`.

• AttributeError: 'NoneType' object has no attribute 'set_tag'

  cause You are trying to call methods like `set_tag()` on a span object that is `None`. This typically happens if `tracing.get_span()` returns `None`, meaning no active span was found for the current request.
  fix Always check if the span is not `None` before using it: `span = tracing.get_span(); if span: span.set_tag(...)`. Ensure `trace_all_requests=True` during `FlaskTracing` initialization or use explicit tracing decorators if only specific routes should be traced.

• AttributeError: 'MockTracer' object has no attribute 'active_span'

  cause This error occurs when trying to access `active_span` directly on an `opentracing.Tracer` object (like `MockTracer`) or via `opentracing.tracer.active_span` with `opentracing-api` v2.x. `flask-opentracing` v1.0.0+ is designed for `opentracing-api` v2.x, which changed how active spans are managed.
  fix Use `tracing.get_span()` (where `tracing` is your `FlaskTracing` instance) to retrieve the active span managed by `flask-opentracing`.

Warnings

• breaking `flask-opentracing` v1.0.0 and newer versions require `opentracing-api` v2.0 or higher. If upgrading from `flask-opentracing` 0.x, ensure your `opentracing-api` dependency is also updated to v2.x to avoid compatibility issues.
  Fix: Ensure `opentracing` (or `opentracing_api`) is installed at version 2.0 or higher (`pip install opentracing>=2.0`).
• breaking As of `flask-opentracing` v1.0.0, the `FlaskTracing` constructor explicitly requires an `opentracing.Tracer` instance as its first argument. The older implicit use of `opentracing.tracer` (from `opentracing-api` v1.x) is no longer supported.
  Fix: Pass an initialized tracer object (e.g., `MockTracer()`, `jaeger_client.Config().initialize_tracer()`) directly to `FlaskTracing(tracer_instance, app=app, ...)`.
• gotcha When trying to access the current span, always use `tracing.get_span()` (where `tracing` is your `FlaskTracing` instance). Do not use `opentracing.tracer.active_span` or similar global access patterns, which are deprecated or removed in `opentracing-api` v2.x and not compatible with `flask-opentracing` v1.0.0+.
  Fix: Replace `opentracing.tracer.active_span` with `your_tracing_instance.get_span()`.
• gotcha For production deployments, `MockTracer` should be replaced with a real distributed tracing client (e.g., Jaeger, Zipkin). `MockTracer` only collects spans in memory and does not send them to a tracing backend.
  Fix: Install and configure a specific tracer client (e.g., `pip install jaeger-client`) and initialize `FlaskTracing` with it: `from jaeger_client import Config; config = Config(service_name='my-app'); tracer = config.initialize_tracer(); FlaskTracing(tracer, app=app)`.

Install

• pip install flask-opentracing Install latest version

Imports

• FlaskTracing

  from flask_opentracing import FlaskTracing

Quickstart

This quickstart initializes a Flask application with `FlaskTracing`, using a `MockTracer` for demonstration. It configures `trace_all_requests=True` to automatically trace all incoming HTTP requests. Custom spans and tags can be added within routes by retrieving the current span using `tracing.get_span()`.

from flask import Flask
from flask_opentracing import FlaskTracing
from opentracing.mocktracer import MockTracer

app = Flask(__name__)

# Initialize FlaskTracing with an OpenTracing-compatible tracer.
# For production, replace MockTracer with a real tracer like Jaeger or Zipkin.
# e.g., from jaeger_client import Config; tracer = Config(service_name='my-app').initialize_tracer()
# Use os.environ.get for dynamic configuration if needed.
tracing = FlaskTracing(MockTracer(), app=app, trace_all_requests=True)

@app.route('/')
def hello():
    # Get the current active span for manual instrumentation
    span = tracing.get_span()
    if span:
        span.set_tag('hello-to', 'world')
    return "Hello World!"

@app.route('/greet/<name>')
def greet(name):
    span = tracing.get_span()
    if span:
        span.set_tag('greeting-name', name)
    return f"Hello, {name}!"

if __name__ == '__main__':
    app.run(debug=True)