Registry /
observability / opentelemetry-instrumentation-tornado
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.636s · 55.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 0.560s · 54MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TornadoInstrumentor
✓ from opentelemetry.instrumentation.tornado import TornadoInstrumentor
This is the main class to instantiate and call .instrument() on.
This quickstart demonstrates how to instrument a basic Tornado application. It sets up the OpenTelemetry SDK with a console exporter to print traces, then applies the Tornado instrumentation before the application starts. Requests to the server will generate and export traces.
import tornado.ioloop
import tornado.web
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
from opentelemetry.instrumentation.tornado import TornadoInstrumentor
# 1. Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "tornado-app"})
provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument Tornado
TornadoInstrumentor().instrument()
class MainHandler(tornado.web.RequestHandler):
def get(self):
self.write("Hello, Tornado OpenTelemetry!")
def make_app():
return tornado.web.Application([
(r"/", MainHandler),
])
if __name__ == "__main__":
app = make_app()
app.listen(8888)
print("Tornado server listening on http://localhost:8888")
print("Visit http://localhost:8888 to see traces in console.")
tornado.ioloop.IOLoop.current().start()
Debug
Known issues
gotchaThis instrumentation library is currently in beta. While generally functional, it may introduce breaking changes or performance issues and should be used with caution in production environments.fixMonitor GitHub releases and OpenTelemetry Python documentation for stability updates and migration guides.
affects: All versions (0.x.x series)
gotchaWhen using multi-process or forking web servers (e.g., Gunicorn with multiple workers) with OpenTelemetry Python auto-instrumentation, metrics generation can become inconsistent. This is due to how forking interacts with background threads and locks in key OpenTelemetry SDK components.fixConsider running with a single worker process or using programmatic auto-instrumentation for better control. Consult OpenTelemetry Python troubleshooting guides for specific workarounds.
affects: All versions
gotchaTo capture specific HTTP request or response headers as span attributes, you must explicitly configure them via environment variables: `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`. Header names in Tornado are case-insensitive for capture purposes.fixSet environment variables like `export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST='Content-Type,X-Request-ID'`. Captured header names will be normalized to `http.request.header.<header_name>`.
affects: All versions
gotchaPaths can be excluded from automatic tracing using the `OTEL_PYTHON_TORNADO_EXCLUDED_URLS` environment variable (or `OTEL_PYTHON_EXCLUDED_URLS` for all instrumentations). Additionally, custom request attributes can be traced using `OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS`.fixSet environment variables, e.g., `export OTEL_PYTHON_TORNADO_EXCLUDED_URLS='/healthz'` or `export OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS='uri,query'`.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
tornadorequiredThe web framework being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry signals.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-instrumentationrequiredCommon utilities and base classes for OpenTelemetry instrumentations.
opentelemetry-semantic-conventionsrequiredStandardized attribute names for telemetry.
opentelemetry-util-httprequiredUtilities for HTTP-related instrumentation.
opentelemetry-exporter-otlpoptionalA common exporter for sending telemetry data via OTLP (OpenTelemetry Protocol).