opentracing-utils 0.22.1

BasicTracer

This is the basic noop tracer. It could be initialized with a recorder (e.g. Memory Recorder), which can be useful in debugging and playing around with OpenTracing concepts.

import opentracing
from opentracing_utils import OPENTRACING_BASIC, init_opentracing_tracer

# Initialize upon application start
init_opentracing_tracer(OPENTRACING_BASIC)

# It is possible to pass custom recorder
# init_opentracing_tracer(OPENTRACING_BASIC, recorder=custom_recorder)

# Now use the opentracing.tracer
root_span = opentracing.tracer.start_span(operation_name='root_span')

Instana

import opentracing
from opentracing_utils import OPENTRACING_INSTANA, init_opentracing_tracer

# Initialize upon application start
init_opentracing_tracer(OPENTRACING_INSTANA)

# It is possible to pass args
# init_opentracing_tracer(OPENTRACING_INSTANA, service='python-server')

# Now use the opentracing.tracer
root_span = opentracing.tracer.start_span(operation_name='root_span')

Jaeger

import opentracing
from opentracing_utils import OPENTRACING_JAEGER, init_opentracing_tracer

# Initialize upon application start
init_opentracing_tracer(OPENTRACING_JAEGER)

# It is possible to pass args
# init_opentracing_tracer(OPENTRACING_JAEGER, service_name='python-server', config=custom_config_with_sampling)

# Now use the opentracing.tracer
root_span = opentracing.tracer.start_span(operation_name='root_span')

LightStep

import opentracing
from opentracing_utils import OPENTRACING_LIGHTSTEP, init_opentracing_tracer

# Initialize upon application start
init_opentracing_tracer(OPENTRACING_LIGHTSTEP)

# It is possible to pass args
# init_opentracing_tracer(OPENTRACING_LIGHTSTEP, component_name='python-server', access_token='123', collector_host='production-collector.com')

# Now use the opentracing.tracer
root_span = opentracing.tracer.start_span(operation_name='root_span')

Skip Spans

In certain cases you might need to skip certain spans while using the @trace decorator.

def skip_this_span(arg1, arg2, **kwargs):
    if arg1 == 'special':
        # span should be skipped
        return True

    return False


@trace(skip_span=skip_this_span)
def traced(arg1, arg2):
    pass


top_span = opentracing.tracer.start_span(operation_name='top_trace')
with top_span:
    # this call will be traced and have a span!
    traced('open', 'tracing')

    # this call won't be traced and no span to be added!
    traced('special', 'tracing')

Broken traces

If you plan to break nested traces, then it is recommended to pass the span to traced functions

top_span = opentracing.tracer.start_span(operation_name='top_trace')
with top_span:

    # This one gets ``top_span`` as parent span
    call_traced()

    # Here, we break the trace, since we create a new span with no parents
    broken_span = opentracing.tracer.start_span(operation_name='broken_trace')
    with broken_span:
        # This one gets ``broken_span`` as parent span (not consistent in 2.7 and 3.5)
        call_traced()

        # pass span as safer/guaranteed trace here
        call_traced(span=broken_span)

    # ISSUE: Due to stack call inspection, next call will get ``broken_span`` instead of ``top_span``, which is wrong!!
    call_traced()

    # To get the ``top_span`` as parent span, then pass it to the traced call
    call_traced(span=top_span)

Multiple traces

If you plan to use multiple traces then it is better to always pass the span as it is safer/guaranteed.

first_span = opentracing.tracer.start_span(operation_name='first_trace')
with first_span:

    # This one gets ``first_span`` as parent span
    call_traced()

second_span = opentracing.tracer.start_span(operation_name='second_trace')
with second_span:

    # ISSUE: This one **could** get ``first_span`` as parent span (not consistent among Python versions)
    call_traced()

    # It is better to pass ``second_span`` explicitly
    call_traced(span=second_span)

Generators (yield)

Using generators could get tricky and leads to invalid parent span inspection. It is recommended to pass the span explicitly.

@trace(pass_span=True)
def gen(**kwargs):
    s = extract_span_from_kwargs(**kwargs)  # noqa

    # Extract and pass span to ``f2()`` otherwise it could get ``f1()`` as parent span instead of ``gen()``
    f2(span=s)

    for i in range(10):
        yield i

@trace()
def f2():
    pass

@trace()
def f1():
    list(gen())

first_span = opentracing.tracer.start_span(operation_name='first_trace')
with first_span:
    f1()

Django

For tracing Django applications. You can use the following:

• OpenTracingHttpMiddleware: for tracing incoming HTTP requests

# In settings.py or equivalent Django config
from opentracing_utils import init_opentracing_tracer
init_opentracing_tracer(YOUR_TRACER)  # make sure opentracing.tracer is initialized properly.

MIDDLEWARE = (
'opentracing_utils.OpenTracingHttpMiddleware',  # goes first in the list
# ... more middlewares here
)

# Further options

# Add default tags to all incoming HTTP requests spans
OPENTRACING_UTILS_DEFAULT_TAGS = {'my-default-tag': 'tag-value'}

# Add error tag on 4XX responses (default is ``True``)
OPENTRACING_UTILS_ERROR_4XX = False

# Override span operation_name (default is ``view_func.__name__``)
OPENTRACING_UTILS_OPERATION_NAME_CALLABLE = 'my_app.utils.span_operation_name'

# Exclude certain requests from OpenTracing
OPENTRACING_UTILS_SKIP_SPAN_CALLABLE = 'my_app.utils.skip_span'

Here are the callables examples for overriding span operation names and skipping spans:

# my_app/utils.py
def span_operation_name(request, view_func, view_args, view_kwargs):
    return 'edge_{}'.format(view_func.__name__)

def skip_span(request, view_func, view_args, view_kwargs):
    if view_func.__name__.startswith('no_trace_'):
        return True
    return False

In order to follow traces in your views, you can use extract_span_from_django_request utility function.

# my_app/views.py

from opentracing_utils import trace, extract_span_from_django_request

@trace(span_extractor=extract_span_from_django_request, operation_name='custom_view')
def my_traced_view(request):
    ...

Flask

For tracing Flask applications. This utility function adds a middleware that handles all incoming requests to the Flask application.

from opentracing_utils import trace_flask, extract_span_from_flask_request
from flask import Flask

app = Flask(__name__)

trace_flask(app)

# You can add default_tags or optionally treat 4xx responses as not an error (i.e no error tag in span)
# trace_flask(app, default_tags={'always-there': True}, error_on_4xx=False)

# Extract current span from request context
def internal_function():
    current_span = extract_span_from_flask_request()

    current_span.set_tag('internal', True)

# You can skip requests spans.
def skip_health_checks(request):
    return request.path == '/health'

# trace_flask(skip_span=skip_health_checks)

Requests

For tracing requests client library for all outgoing requests.

# trace_requests should be called as early as possible, before importing requests
from opentracing_utils import trace_requests
trace_requests()  # noqa

# In case you want to include default span tags to be sent with every outgoing request.
# trace_requests(default_tags={'account_id': '123'}, set_error_tag=False)

# In case you want to keep the URL query args (masked by default in order to avoid leaking auth tokens etc...)
# trace_requests(mask_url_query=False)

# You can also mask URL path parameters (e.g. http://hostname/1 will be http://hostname/??/)
# trace_requests(mask_url_path=True)

# The library patches the requests library send functionality. This causes
# all requests to propagate the span id's in the headers. Sometimes this is
# undesireable so it's also possible to avoid tracing specific URL's or
# endpoints. trace_requests accepts a list of regex patterns and matches the
# request.url against these patterns, ignoring traces if any pattern matches.
# trace_requests(ignore_url_patterns=[r".*hostname/endpoint"])

import requests

def main():

    span = opentracing.tracer.start_span(operation_name='main')
    with span:
        # Following call will be traced as a ``child span`` and propagated via HTTP headers.
        requests.get('https://example.org')

SQLAlchemy

For tracing SQLAlchemy client library for all SQL queries.

# trace_sqlalchemy can be used to trace all SQL queries.
# By default, span operation_name will be deduced from the query statement (e.g. select, update, delete).
from opentracing_utils import trace_sqlalchemy
trace_sqlalchemy()

# You can customize the span operation_name via supplying a callable
def get_sqlalchemy_span_op_name(conn, cursor, statement, parameters, context, executemany):
    # inspect statement and parameters etc...
    return 'custom_operation_name'
# trace_sqlalchemy(operation_name=get_sqlalchemy_span_op_name)

# By default, trace_sqlalchemy will not set error tags for SQL errors/exceptions. You can change that via ``set_error_tag`` param.
# trace_sqlalchemy(set_error_tag=True)

# you can skip spans for certain SQL queries.
def skip_inserts(conn, cursor, statement, parameters, context, executemany):
    return statement.lower().startswith('insert')

# trace_sqlalchemy(skip_span=skip_inserts)

# you can enrich the span with by supplying an ``enrich_span`` callable.
def enrich_sql_span_parameters(span, conn, cursor, statement, parameters, context, executemany):
    span.set_tag('parameters', parameters)

# trace_sqlalchemy(enrich_span=enrich_sql_span_parameters)