OpenTelemetry Tornado Instrumentation

This library uses OpenTelemetry to track web requests in Tornado applications.

Usage

import tornado.web
from opentelemetry.instrumentation.tornado import TornadoInstrumentor

# apply tornado instrumentation
TornadoInstrumentor().instrument()

class Handler(tornado.web.RequestHandler):
    def get(self):
        self.set_status(200)

app = tornado.web.Application([(r"/", Handler)])
app.listen(8080)
tornado.ioloop.IOLoop.current().start()

Configuration

The following environment variables are supported as configuration options:

  • OTEL_PYTHON_TORNADO_EXCLUDED_URLS

A comma separated list of paths that should not be automatically traced. For example, if this is set to

export OTEL_PYTHON_TORNADO_EXLUDED_URLS='/healthz,/ping'

Then any requests made to /healthz and /ping will not be automatically traced.

Request attributes

To extract certain attributes from Tornado’s request object and use them as span attributes, set the environment variable OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS to a comma delimited list of request attribute names.

For example,

export OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS='uri,query'

will extract path_info and content_type attributes from every traced request and add them as span attributes.

Request/Response hooks

Tornado instrumentation supports extending tracing behaviour with the help of hooks. Its instrument() method accepts three optional functions that get called back with the created span and some other contextual information. Example:

# will be called for each incoming request to Tornado
# web server. `handler` is an instance of
# `tornado.web.RequestHandler`.
def server_request_hook(span, handler):
    pass

# will be called just before sending out a request with
# `tornado.httpclient.AsyncHTTPClient.fetch`.
# `request` is an instance of ``tornado.httpclient.HTTPRequest`.
def client_request_hook(span, request):
    pass

# will be called after a outgoing request made with
# `tornado.httpclient.AsyncHTTPClient.fetch` finishes.
# `response`` is an instance of ``Future[tornado.httpclient.HTTPResponse]`.
def client_resposne_hook(span, future):
    pass

# apply tornado instrumentation with hooks
TornadoInstrumentor().instrument(
    server_request_hook=server_request_hook,
    client_request_hook=client_request_hook,
    client_response_hook=client_resposne_hook
)

API

class opentelemetry.instrumentation.tornado.TornadoInstrumentor(*args, **kwargs)[source]

Bases: opentelemetry.instrumentation.instrumentor.BaseInstrumentor

patched_handlers = []
original_handler_new = None
instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or setup.py.

For example, if an instrumentation instruments requests 1.x, this method should look like:

def instrumentation_dependencies(self) -> Collection[str]:

return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.

Return type

Collection[str]

opentelemetry.instrumentation.tornado.patch_handler_class(tracer, cls, request_hook=None)[source]
opentelemetry.instrumentation.tornado.unpatch_handler_class(cls)[source]