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_EXCLUDED_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
)

Capture HTTP request and response headers

You can configure the agent to capture predefined HTTP headers as span attributes, according to the semantic convention.

Request headers

To capture predefined HTTP request headers as span attributes, set the environment variable OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST to a comma-separated list of HTTP header names.

For example,

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header"

will extract content-type and custom_request_header from request headers and add them as span attributes.

It is recommended that you should give the correct names of the headers to be captured in the environment variable. Request header names in tornado are case insensitive. So, giving header name as CUStomHeader in environment variable will be able capture header with name customheader.

The name of the added span attribute will follow the format http.request.header.<header_name> where <header_name> being the normalized HTTP header name (lowercase, with - characters replaced by _ ). The value of the attribute will be single item list containing all the header values.

Example of the added span attribute, http.request.header.custom_request_header = ["<value1>,<value2>"]

Response headers

To capture predefined HTTP response headers as span attributes, set the environment variable OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE to a comma-separated list of HTTP header names.

For example,

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header"

will extract content-type and custom_response_header from response headers and add them as span attributes.

It is recommended that you should give the correct names of the headers to be captured in the environment variable. Response header names captured in tornado are case insensitive. So, giving header name as CUStomHeader in environment variable will be able capture header with name customheader.

The name of the added span attribute will follow the format http.response.header.<header_name> where <header_name> being the normalized HTTP header name (lowercase, with - characters replaced by _ ). The value of the attribute will be single item list containing all the header values.

Example of the added span attribute, http.response.header.custom_response_header = ["<value1>,<value2>"]

Note

Environment variable names to capture http headers are still experimental, and thus are subject to change.

API

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

Bases: 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 pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

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.

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

opentelemetry.instrumentation.tornado.unpatch_handler_class(cls)[source]