Registry /
observability / opentelemetry-instrumentation-falcon
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.000s · 24.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.000s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FalconInstrumentor
✓ from opentelemetry.instrumentation.falcon import FalconInstrumentor
✗ import falcon; app = falcon.App(); FalconInstrumentor().instrument()
Instrumentation must occur *before* the Falcon application instance is created to ensure all hooks are applied correctly.
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.
import falcon
from opentelemetry.instrumentation.falcon import FalconInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "my-falcon-app"})
provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)
trace.set_tracer_provider(provider)
# Instrument Falcon BEFORE creating the app instance
FalconInstrumentor().instrument()
class HelloResource:
def on_get(self, req, resp):
resp.status = falcon.HTTP_200
resp.media = {'message': 'Hello World'}
app = falcon.App()
app.add_route('/hello', HelloResource())
# To run this app (e.g., using Gunicorn):
# gunicorn -b 127.0.0.1:8000 your_module_name:app
# Then access http://127.0.0.1:8000/hello
opentelemetry-instrument --version
Debug
Known issues
gotchaThe 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.fixEnsure `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`).
affects: All versions
gotchaRunning 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.fixAvoid 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.
affects: All versions
gotchaTo 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.fixDefine `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"`.
affects: All versions
deprecatedFalcon 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.fixMigrate your Falcon application to use `falcon.App()` instead of `falcon.API()` for creating your application instance.
affects: Falcon 3.x and newer
gotchaAs 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.fixRegularly 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.
affects: All beta versions
gotchaFor 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.fixInstall `opentelemetry-instrumentation-asgi` and ensure both instrumentors are enabled in your ASGI Falcon application. `pip install opentelemetry-instrumentation-asgi`.
affects: All versions when using ASGI
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
falconrequiredThe web framework being instrumented.
opentelemetry-apirequiredCore OpenTelemetry API for tracing.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry data.
opentelemetry-instrumentation-wsgirequiredFalcon instrumentation builds on the WSGI middleware for HTTP request tracking.
opentelemetry-semantic-conventionsrequiredProvides standard attribute names for telemetry data.
opentelemetry-util-httprequiredUtility functions for HTTP instrumentation.