{"id":2631,"library":"opentelemetry-instrumentation-falcon","title":"OpenTelemetry Falcon Instrumentation","description":"OpenTelemetry Falcon instrumentation provides automatic tracing for HTTP requests in Falcon web applications. It captures request flow, uses Falcon resource and method names as span names, and records errors. Currently at version 0.62b0, this library is part of the broader opentelemetry-python-contrib project, which often releases beta versions in sync with the core OpenTelemetry Python SDK's release cadence, indicating active development.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["observability","opentelemetry","falcon","instrumentation","tracing","wsgi","asgi"],"install":[{"cmd":"pip install opentelemetry-instrumentation-falcon opentelemetry-sdk","lang":"bash","label":"Install Falcon Instrumentation and OpenTelemetry SDK"}],"dependencies":[{"reason":"The web framework being instrumented.","package":"falcon","optional":false},{"reason":"Core OpenTelemetry API for tracing.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK for processing and exporting telemetry data.","package":"opentelemetry-sdk","optional":false},{"reason":"Falcon instrumentation builds on the WSGI middleware for HTTP request tracking.","package":"opentelemetry-instrumentation-wsgi","optional":false},{"reason":"Provides standard attribute names for telemetry data.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Utility functions for HTTP instrumentation.","package":"opentelemetry-util-http","optional":false}],"imports":[{"note":"Instrumentation must occur *before* the Falcon application instance is created to ensure all hooks are applied correctly.","wrong":"import falcon; app = falcon.App(); FalconInstrumentor().instrument()","symbol":"FalconInstrumentor","correct":"from opentelemetry.instrumentation.falcon import FalconInstrumentor"}],"quickstart":{"code":"import falcon\nfrom opentelemetry.instrumentation.falcon import FalconInstrumentor\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"my-falcon-app\"})\nprovider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(span_processor)\ntrace.set_tracer_provider(provider)\n\n# Instrument Falcon BEFORE creating the app instance\nFalconInstrumentor().instrument()\n\nclass HelloResource:\n    def on_get(self, req, resp):\n        resp.status = falcon.HTTP_200\n        resp.media = {'message': 'Hello World'}\n\napp = falcon.App()\napp.add_route('/hello', HelloResource())\n\n# To run this app (e.g., using Gunicorn):\n# gunicorn -b 127.0.0.1:8000 your_module_name:app\n# Then access http://127.0.0.1:8000/hello","lang":"python","description":"This quickstart demonstrates how to instrument a basic Falcon application using `FalconInstrumentor`. Ensure the OpenTelemetry SDK is configured and `FalconInstrumentor().instrument()` is called before creating your `falcon.App()` instance. This example uses a `ConsoleSpanExporter` for immediate feedback to the console."},"warnings":[{"fix":"Ensure `opentelemetry.sdk` setup and `FalconInstrumentor().instrument()` are called at the very start of your application, ideally before any `import falcon` statement, or by using OpenTelemetry's auto-instrumentation launcher (`opentelemetry-instrument`).","message":"The OpenTelemetry SDK (including instrumentors) must be initialized *before* any instrumented library (like Falcon) is imported. If `falcon` is imported first, instrumentation hooks may not be applied, leading to missing telemetry data.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using hot-reload/reloader modes when running instrumented applications. For development, restart the application manually after code changes or use a different approach for code reloading if available.","message":"Running the Falcon application in reloader/hot-reload mode (e.g., with `gunicorn --reload` or similar development server options) can interfere with OpenTelemetry's instrumentation process, leading to broken or incomplete tracing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Define `OTEL_PYTHON_FALCON_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`) with precise regex patterns to match URLs that should not be traced. For example: `export OTEL_PYTHON_FALCON_EXCLUDED_URLS=\"/healthz,/metrics\"`.","message":"To exclude specific URLs (e.g., health check endpoints) from being traced, set the environment variables `OTEL_PYTHON_FALCON_EXCLUDED_URLS` or the more general `OTEL_PYTHON_EXCLUDED_URLS` to a comma-delimited string of regular expressions. Incorrectly configuring these can lead to noisy or costly telemetry data.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate your Falcon application to use `falcon.App()` instead of `falcon.API()` for creating your application instance.","message":"Falcon 3.x deprecated `falcon.API` in favor of `falcon.App`. While the instrumentation currently supports both, relying on the deprecated `falcon.API` might lead to issues or missed instrumentation in future versions if the alias is removed or not fully covered.","severity":"deprecated","affected_versions":"Falcon 3.x and newer"},{"fix":"Regularly review the `opentelemetry-python-contrib` changelog for `opentelemetry-instrumentation-falcon` before upgrading. Be prepared to adjust your code or monitoring dashboards if semantic conventions or API calls change.","message":"As a beta package (indicated by `b0` suffix), `opentelemetry-instrumentation-falcon` may undergo more frequent breaking changes to its API, internal implementation, or the semantic conventions it uses for generated telemetry data compared to stable OpenTelemetry components. This may require more frequent updates to your application or observability backend configuration.","severity":"gotcha","affected_versions":"All beta versions"},{"fix":"Install `opentelemetry-instrumentation-asgi` and ensure both instrumentors are enabled in your ASGI Falcon application. `pip install opentelemetry-instrumentation-asgi`.","message":"For ASGI (Asynchronous Server Gateway Interface) Falcon applications, you should use `opentelemetry-instrumentation-asgi` in conjunction with `opentelemetry-instrumentation-falcon` to ensure proper tracing of the ASGI layer.","severity":"gotcha","affected_versions":"All versions when using ASGI"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}