Flask-OpenTracing
This package enables distributed tracing in Flask applications via The OpenTracing Project. Once a production system contends with real concurrency or splits into many services, crucial (and formerly easy) tasks become difficult: user-facing latency optimization, root-cause analysis of backend errors, communication about distinct pieces of a now-distributed system, etc. Distributed tracing follows a request on its journey from inception to completion from mobile/browser all the way to the microservices.
As core services and libraries adopt OpenTracing, the application builder is no longer burdened with the task of adding basic tracing instrumentation to their own code. In this way, developers can build their applications with the tools they prefer and benefit from built-in tracing instrumentation. OpenTracing implementations exist for major distributed tracing systems and can be bound or swapped with a one-line configuration change.
If you want to learn more about the underlying python API, visit the python source code.
If you are migrating from the 0.x series, you may want to read the list of breaking changes.
Installation
Run the following command:
$ pip install Flask-Opentracing
Usage
This Flask extension allows for tracing of Flask apps using the OpenTracing API. All that it requires is for a FlaskTracing tracer to be initialized using an instance of an OpenTracing tracer. You can either trace all requests to your site, or use function decorators to trace certain individual requests.
Note: optional_args in both cases are any number of attributes (as strings) of flask.Request that you wish to set as tags on the created span
Initialize
FlaskTracing wraps the tracer instance that's supported by opentracing. To create a FlaskTracing object, you can either pass in a tracer object directly or a callable that returns the tracer object. For example:
import opentracing
from flask_opentracing import FlaskTracing
opentracing_tracer = ## some OpenTracing tracer implementation
tracing = FlaskTracing(opentracing_tracer, ...)
or
import opentracing
from flask_opentracing import FlaskTracing
def initialize_tracer():
...
return opentracing_tracer
tracing = FlaskTracing(initialize_tracer, ...)
Trace All Requests
import opentracing
from flask_opentracing import FlaskTracing
app = Flask(__name__)
opentracing_tracer = ## some OpenTracing tracer implementation
tracing = FlaskTracing(opentracing_tracer, True, app, [optional_args])
Trace Individual Requests
import opentracing
from flask_opentracing import FlaskTracing
app = Flask(__name__)
opentracing_tracer = ## some OpenTracing tracer implementation
tracing = FlaskTracing(opentracing_tracer)
@app.route('/some_url')
@tracing.trace(optional_args)
def some_view_func():
...
return some_view
Accessing Spans Manually
In order to access the span for a request, we've provided an method FlaskTracing.get_span(request) that returns the span for the request, if it is exists and is not finished. This can be used to log important events to the span, set tags, or create child spans to trace non-RPC events. If no request is passed in, the current request will be used.
Tracing an RPC
If you want to make an RPC and continue an existing trace, you can inject the current span into the RPC. For example, if making an http request, the following code will continue your trace across the wire:
@tracing.trace()
def some_view_func(request):
new_request = some_http_request
current_span = tracing.get_span(request)
text_carrier = {}
opentracing_tracer.inject(span, opentracing.Format.TEXT_MAP, text_carrier)
for k, v in text_carrier.iteritems():
new_request.add_header(k,v)
... # make request
Examples
See examples to view and run an example of two Flask applications with integrated OpenTracing tracers.
This tutorial has a step-by-step guide for using Flask-Opentracing with Jaeger.
Breaking changes from 0.x
Starting with the 1.0 version, a few changes have taken place from previous versions:
FlaskTracerhas been renamed toFlaskTracing, althoughFlaskTracingcan be used still as a deprecated name.- When passing an
Applicationobject atFlaskTracingcreation time,trace_all_requestsdefaults toTrue. - When no
opentracing.Traceris provided,FlaskTracingwill rely on the global tracer.
Further Information
If you're interested in learning more about the OpenTracing standard, please visit opentracing.io or join the mailing list. If you would like to implement OpenTracing in your project and need help, feel free to send us a note at [email protected].
1 Dec 15, 2021
19 Dec 02, 2022
248 Dec 26, 2022
922 Jan 08, 2023
3 Jul 03, 2022
0 Feb 02, 2022
2.2k Dec 28, 2022
13 Jul 14, 2022
1 Oct 28, 2021
6 Jan 06, 2023
2 Jan 31, 2022
549 Nov 10, 2022
4 Jul 14, 2022
246 Dec 28, 2022
4 Jul 17, 2022
2 Sep 28, 2022
10 Dec 08, 2022
617 Dec 30, 2022
1 Oct 20, 2021
9 Feb 11, 2022