Package: signalfx-instrumentation-django
This package enables distributed tracing in Django projects 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-djangoSetting up TracingIn order to implement tracing in your system, add the following lines of code to your site’s settings.py file:importdjango_opentracing# OpenTracing settings# if not included, defaults to True.# has to come before OPENTRACING_TRACING setting because python...OPENTRACING_TRACE_ALL=True# defaults to []# only valid if OPENTRACING_TRACE_ALL == TrueOPENTRACING_TRACED_ATTRIBUTES=['arg1','arg2']# Callable that returns an `opentracing.Tracer` implementation.OPENTRACING_TRACER_CALLABLE='opentracing.Tracer'# Parameters for the callable (Depending on the tracer implementation chosen)OPENTRACING_TRACER_PARAMETERS={'example-parameter-host':'collector',}If you want to directly override theDjangoTracingused, you can use the following. This may cause import loops (See #10)# some_opentracing_tracer can be any valid OpenTracing tracer implementationOPENTRACING_TRACING=django_opentracing.DjangoTracing(some_opentracing_tracer)Note:Valid request attributes to trace are listed [here](https://docs.djangoproject.com/en/1.9/ref/request-response/#django.http.HttpRequest). When you trace an attribute, this means that created spans will have tags with the attribute name and the request’s value.Tracing All RequestsIn order to trace all requests,OPENTRACING_TRACE_ALLneeds to be set toTrue(the default). If you want to trace any attributes for all requests, then add them toOPENTRACING_TRACED_ATTRIBUTES. For example, if you wanted to trace the path and method, then setOPENTRACING_TRACED_ATTRIBUTES = ['path', 'method'].Tracing all requests uses the middleware django_opentracing.OpenTracingMiddleware, so add this to your settings.py file’sMIDDLEWARE_CLASSESat the top of the stack.MIDDLEWARE_CLASSES=['django_opentracing.OpenTracingMiddleware',...# other middleware classes]Tracing Individual RequestsIf you don’t want to trace all requests to your site, setOPENTRACING_TRACE_ALLtoFalse. Then you can use function decorators to trace individual view functions. This can be done by adding the following lines of code to views.py (or any other file that has url handler functions):fromdjango.confimportsettingstracing=settings.OPENTRACING_TRACING@tracing.trace(optional_args)defsome_view_func(request):...# do some stuffThis tracing method doesn’t use middleware, so there’s no need to add it to your settings.py file.The optional arguments allow for tracing of request attributes. For example, if you want to trace metadata, you could pass in@tracing.trace('META')andrequest.METAwould be set as a tag on all spans for this view function.Note:IfOPENTRACING_TRACE_ALLis set toTrue, this decorator will be ignored, including any traced request attributes.Accessing Spans ManuallyIn order to access the span for a request, we’ve provided an methodDjangoTracing.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.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.items():request.add_header(k,v)...# make requestExampleHere is anexampleof a Django application that acts as both a client and server,
with integrated OpenTracing tracers.Breaking changes from 0.xStarting with the 1.0 version, a few changes have taken place from previous versions:DjangoTracerhas been renamed toDjangoTracing, althoughDjangoTracercan be used still as a deprecated name. Likewise forOPENTRACING_TRACERbeing renamed toOPENTRACING_TRACING.When using the middleware layer,OPENTRACING_TRACE_ALLdefaults toTrue.When noopentracing.Traceris provided,DjangoTracingwill 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.