Package: signalfx-instrumentation-flask
This package enables distributed tracing in Flask applications viaThe 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 pythonsource code.If you are migrating from the 0.x series, you may want to read the list ofbreaking changes.InstallationRun the following command:$ pip install signalfx-instrumentation-flaskUsageThis Flask extension allows for tracing of Flask apps using the OpenTracing API. All
that it requires is for aFlaskTracingtracer 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_argsin both cases are any number of attributes (as strings) offlask.Requestthat you wish to set as tags on the created spanInitializeFlaskTracingwraps the tracer instance that’s supported by opentracing. To create aFlaskTracingobject, you can either pass in a tracer object directly or a callable that returns the tracer object. For example:importopentracingfromflask_opentracingimportFlaskTracingopentracing_tracer=## some OpenTracing tracer implementationtracing=FlaskTracing(opentracing_tracer,...)orimportopentracingfromflask_opentracingimportFlaskTracingdefinitialize_tracer():...returnopentracing_tracertracing=FlaskTracing(initialize_tracer,...)Trace All Requestsimportopentracingfromflask_opentracingimportFlaskTracingapp=Flask(__name__)opentracing_tracer=## some OpenTracing tracer implementationtracing=FlaskTracing(opentracing_tracer,True,app,[optional_args])Trace Individual Requestsimportopentracingfromflask_opentracingimportFlaskTracingapp=Flask(__name__)opentracing_tracer=## some OpenTracing tracer implementationtracing=FlaskTracing(opentracing_tracer)@app.route('/some_url')@tracing.trace(optional_args)defsome_view_func():...returnsome_viewAccessing Spans ManuallyIn order to access the span for a request, we’ve provided an methodFlaskTracing.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 RPCIf 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()defsome_view_func(request):new_request=some_http_requestcurrent_span=tracing.get_span(request)text_carrier={}opentracing_tracer.inject(span,opentracing.Format.TEXT_MAP,text_carrier)fork,vintext_carrier.iteritems():new_request.add_header(k,v)...# make requestFlaskScopeManagerBy default, Flask-OpenTracing will attempt to track spans initiated by view functions in the request context.  However, to fully ensure parent-child span relationships throughout your Flask application in any deployment configuration, a FlaskScopeManager is provided.frommy_opentracing_tracerimportOpenTracingTracerfromflask_opentracingimportFlaskTracer,FlaskScopeManagerapp=Flask(__name__)opentracing_tracer=OpenTracingTracer(FlaskScopeManager())# trace all requeststracing=FlaskTracing(opentracing_tracer,True,app,[optional_args])@app.route('/some_url')defsome_view_func():helper_function()...returnsome_viewdefhelper_function():# spans created in your application will be children of parent spans# automatically created for your traced view function.withopentracing_tracer.start_active_span('MyChildSpan')asscopescope.span.set_tag('HelpfulKey','HelpfulValue')ExamplesSeeexamplesto view and run an example of two Flask applications
with integrated OpenTracing tracers.This tutorialhas a step-by-step guide for usingFlask-OpentracingwithJaeger.Breaking changes from 0.xStarting 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 anApplicationobject atFlaskTracingcreation time,trace_all_requestsdefaults toTrue.When noopentracing.Traceris provided,FlaskTracingwill rely on the
global tracer.Further InformationIf you’re interested in learning more about the OpenTracing standard, please visitopentracing.ioorjoin the mailing list. If you would like to implement OpenTracing in your project and need help, feel free to send us a note atcommunity@opentracing.io.