Skip to main content

Tracing Instrumentation using OpenTracing API (

Project description

[![PyPI version][pypi-img]][pypi] [![Build Status][ci-img]][ci]

# opentracing-python-instrumentation

A collection of instrumentation tools to enable tracing with
[OpenTracing API](

## Usage

This library provides two types of instrumentation, explicit instrumentation
for server endpoints, and implicit instrumentation for client call sites.

Server endpoints are instrumented by creating a middleware class that:

1. initializes the specific tracer implementation
2. wraps incoming request handlers into a method that reads the incoming
tracing info from the request and creates a new tracing Span

Client call sites are instrumented implicitly by executing a set of
available `client_hooks` that monkey-patch some API points in several
common libraries like `SQLAlchemy`, `urllib2`, Tornado Async HTTP Client.
The initialization of those hooks is usually also done from the middleware
class's `__init__` method.

Here's an example of a middleware for
[Clay framework](


from opentracing_instrumentation.request_context import RequestContextManager
from opentracing_instrumentation.http_server import before_request
from opentracing_instrumentation.http_server import WSGIRequestWrapper
from opentracing_instrumentation.client_hooks import install_all_patches

class TracerMiddleware(object):

def __init__(self, app, wsgi_app):
self.wsgi_app = wsgi_app
self.service_name =

CONFIG.app_name = self.service_name

self.wsgi_app = create_wsgi_middleware(wsgi_app)

def __call__(self, environ, start_response):
return self.wsgi_app(environ, start_response)

def init_tracer(self):
# code specific to your tracer implementation

def create_wsgi_middleware(other_wsgi, tracer=None):
Create a wrapper middleware for another WSGI response handler.
If tracer is not passed in, 'opentracing.tracer' is used.

def wsgi_tracing_middleware(environ, start_response):
# TODO find out if the route can be retrieved from somewhere

request = WSGIRequestWrapper.from_wsgi_environ(environ)
span = before_request(request=request, tracer=tracer)

# Wrapper around the real start_response object to log
# additional information to opentracing Span
def start_response_wrapper(status, response_headers, exc_info=None):
if exc_info is not None:
span.add_tag('error', str(exc_info))

return start_response(status, response_headers)

with RequestContextManager(span=span):
return other_wsgi(environ, start_response_wrapper)

return wsgi_tracing_middleware

And here's an example for middleware in Tornado-based app:

class TracerMiddleware(object):

def __init__(self):
# perform initialization similar to above, including installing
# the client_hooks

def __call__(self, request, handler, next_mw):
request_wrapper = http_server.TornadoRequestWrapper(request=request)
span = http_server.before_request(request=request_wrapper)

def next_middleware_with_span():
yield next_mw()

yield run_coroutine_with_span(span=span,


def run_coroutine_with_span(span, func, *args, **kwargs):
"""Wrap the execution of a Tornado coroutine func in a tracing span.

This makes the span available through the get_current_span() function.

:param span: The tracing span to expose.
:param func: Co-routine to execute in the scope of tracing span.
:param args: Positional args to func, if any.
:param kwargs: Keyword args to func, if any.
def mgr():
return RequestContextManager(span)

with tornado.stack_context.StackContext(mgr):
return func(*args, **kwargs)

## Development

virtualenv env
source env/bin/activate
make bootstrap
make test

## Releases

Before new release, add a summary of changes since last version to CHANGELOG.rst

pip install zest.releaser[recommended]
git push origin master --follow-tags
python sdist upload -r pypi
git push


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
opentracing_instrumentation-1.4.0.tar.gz (17.7 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page