{"id":2647,"library":"opentelemetry-instrumentation-tornado","title":"OpenTelemetry Tornado Instrumentation","description":"This library provides instrumentation for the Tornado web framework within OpenTelemetry, capturing request flows and performance metrics for observability. It builds upon OpenTelemetry's WSGI middleware to track web requests. Currently, the library is in beta and designed to integrate with Tornado's asynchronous, high-performance architecture.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","tornado","instrumentation","tracing","observability","apm"],"install":[{"cmd":"pip install opentelemetry-instrumentation-tornado opentelemetry-sdk opentelemetry-exporter-otlp tornado","lang":"bash","label":"Full instrumentation with OTLP exporter and Tornado"}],"dependencies":[{"reason":"The web framework being instrumented.","package":"tornado","optional":false},{"reason":"Core OpenTelemetry API for defining telemetry signals.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for processing and exporting telemetry.","package":"opentelemetry-sdk","optional":false},{"reason":"Common utilities and base classes for OpenTelemetry instrumentations.","package":"opentelemetry-instrumentation","optional":false},{"reason":"Standardized attribute names for telemetry.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Utilities for HTTP-related instrumentation.","package":"opentelemetry-util-http","optional":false},{"reason":"A common exporter for sending telemetry data via OTLP (OpenTelemetry Protocol).","package":"opentelemetry-exporter-otlp","optional":true}],"imports":[{"note":"This is the main class to instantiate and call .instrument() on.","symbol":"TornadoInstrumentor","correct":"from opentelemetry.instrumentation.tornado import TornadoInstrumentor"}],"quickstart":{"code":"import tornado.ioloop\nimport tornado.web\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor\nfrom opentelemetry.instrumentation.tornado import TornadoInstrumentor\n\n# 1. Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"tornado-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = BatchSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Tornado\nTornadoInstrumentor().instrument()\n\nclass MainHandler(tornado.web.RequestHandler):\n    def get(self):\n        self.write(\"Hello, Tornado OpenTelemetry!\")\n\ndef make_app():\n    return tornado.web.Application([\n        (r\"/\", MainHandler),\n    ])\n\nif __name__ == \"__main__\":\n    app = make_app()\n    app.listen(8888)\n    print(\"Tornado server listening on http://localhost:8888\")\n    print(\"Visit http://localhost:8888 to see traces in console.\")\n    tornado.ioloop.IOLoop.current().start()\n","lang":"python","description":"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."},"warnings":[{"fix":"Monitor GitHub releases and OpenTelemetry Python documentation for stability updates and migration guides.","message":"This 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.","severity":"gotcha","affected_versions":"All versions (0.x.x series)"},{"fix":"Consider running with a single worker process or using programmatic auto-instrumentation for better control. Consult OpenTelemetry Python troubleshooting guides for specific workarounds.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set 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>`.","message":"To 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set environment variables, e.g., `export OTEL_PYTHON_TORNADO_EXCLUDED_URLS='/healthz'` or `export OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS='uri,query'`.","message":"Paths 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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}