OpenTelemetry Falcon Instrumentation

0.62b0 · active · verified Fri Apr 10

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.

Warnings

gotcha 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.
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`).
gotcha 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.
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.
gotcha 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.
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"`.
deprecated 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.
Fix: Migrate your Falcon application to use `falcon.App()` instead of `falcon.API()` for creating your application instance.
gotcha 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.
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.
gotcha 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.
Fix: Install `opentelemetry-instrumentation-asgi` and ensure both instrumentors are enabled in your ASGI Falcon application. `pip install opentelemetry-instrumentation-asgi`.

Install

pip install opentelemetry-instrumentation-falcon opentelemetry-sdk Install Falcon Instrumentation and OpenTelemetry SDK

Imports

FalconInstrumentor
```
from opentelemetry.instrumentation.falcon import FalconInstrumentor
```
Instrumentation must occur *before* the Falcon application instance is created to ensure all hooks are applied correctly.

Quickstart

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

view raw JSON →