Add FalconInstrumentor labeler custom attrs metrics support

Author: tammy-baylis-swi

CHANGELOG.md

@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3666](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3666))
 - `opentelemetry-sdk-extension-aws` Add AWS X-Ray Remote Sampler with initial Rules Poller implementation
   ([#3366](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3366))
-- `opentelemetry-instrumentation`, `opentelemetry-instrumentation-flask`, `opentelemetry-instrumentation-wsgi`, `opentelemetry-instrumentation-django`: Add Labeler utility. Add FlaskInstrumentor, DjangoInstrumentor, WsgiInstrumentor support of custom attributes merging for HTTP duration metrics.
+- `opentelemetry-instrumentation`, `opentelemetry-instrumentation-flask`, `opentelemetry-instrumentation-wsgi`, `opentelemetry-instrumentation-django`, `opentelemetry-instrumentation-falcon`: Add Labeler utility. Add FalconInstrumentor, FlaskInstrumentor, DjangoInstrumentor, WsgiInstrumentor support of custom attributes merging for HTTP duration metrics.
   ([#3689](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3689))
 
 ## Version 1.36.0/0.57b0 (2025-07-29)

instrumentation/opentelemetry-instrumentation-falcon/src/opentelemetry/instrumentation/falcon/__init__.py

@@ -180,6 +180,38 @@ def response_hook(span, req, resp):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Custom Metrics Attributes using Labeler
+***************************************
+The Falcon instrumentation reads from a Labeler utility that supports adding custom attributes
+to the HTTP duration metrics recorded by the instrumentation.
+
+
+.. code-block:: python
+
+    import falcon
+    from opentelemetry.instrumentation._labeler import get_labeler
+    from opentelemetry.instrumentation.falcon import FalconInstrumentor
+
+    FalconInstrumentor().instrument()
+
+    app = falcon.App()
+
+    class UserProfileResource:
+        def on_get(self, req, resp, user_id):
+            # Get the labeler for the current request
+            labeler = get_labeler()
+            # Add custom attributes to Falcon instrumentation metrics
+            labeler.add("user_id", user_id)
+            labeler.add("user_type", "registered")
+            # Or, add multiple attributes at once
+            labeler.add_attributes({
+                "feature_flag": "new_ui",
+                "experiment_group": "control"
+            })
+            resp.text = f'User profile for {user_id}'
+
+    app.add_route('/user/{user_id}', UserProfileResource())
+
 API
 ---
 """
@@ -195,6 +227,7 @@ def response_hook(span, req, resp):
 
 import opentelemetry.instrumentation.wsgi as otel_wsgi
 from opentelemetry import context, trace
+from opentelemetry.instrumentation._labeler import enhance_metric_attributes
 from opentelemetry.instrumentation._semconv import (
     HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
     _get_schema_url,
@@ -420,13 +453,17 @@ def _start_response(status, response_headers, *args, **kwargs):
                 duration_attrs = otel_wsgi._parse_duration_attrs(
                     attributes, _StabilityMode.DEFAULT
                 )
+                # Enhance attributes with any custom labeler attributes
+                duration_attrs = enhance_metric_attributes(duration_attrs)
                 self.duration_histogram_old.record(
                     max(round(duration_s * 1000), 0), duration_attrs
                 )
             if self.duration_histogram_new:
                 duration_attrs = otel_wsgi._parse_duration_attrs(
                     attributes, _StabilityMode.HTTP
                 )
+                # Enhance attributes with any custom labeler attributes
+                duration_attrs = enhance_metric_attributes(duration_attrs)
                 self.duration_histogram_new.record(
                     max(duration_s, 0), duration_attrs
                 )

instrumentation/opentelemetry-instrumentation-falcon/tests/app.py

@@ -1,6 +1,10 @@
 import falcon
 from packaging import version as package_version
 
+from opentelemetry.instrumentation._labeler import (
+    get_labeler,
+)
+
 # pylint:disable=R0201,W0613,E0602
 
 
@@ -75,6 +79,21 @@ def on_get(self, req, resp, user_id):
             resp.text = f"Hello user {user_id}"
 
 
+class UserLabelerResource:
+    def on_get(self, req, resp, user_id):
+        labeler = get_labeler()
+        labeler.add("custom_attr", "test_value")
+        labeler.add_attributes({"endpoint_type": "test", "feature_flag": True})
+        # pylint: disable=no-member
+        resp.status = falcon.HTTP_200
+
+        if _parsed_falcon_version < package_version.parse("3.0.0"):
+            # Falcon 1 and Falcon 2
+            resp.body = f"Hello user {user_id}"
+        else:
+            resp.text = f"Hello user {user_id}"
+
+
 def make_app():
     if _parsed_falcon_version < package_version.parse("3.0.0"):
         # Falcon 1 and Falcon 2
@@ -90,5 +109,6 @@ def make_app():
         "/test_custom_response_headers", CustomResponseHeaderResource()
     )
     app.add_route("/user/{user_id}", UserResource())
+    app.add_route("/user_custom_attr/{user_id}", UserLabelerResource())
 
     return app

instrumentation/opentelemetry-instrumentation-falcon/tests/test_falcon.py

@@ -21,6 +21,7 @@
 from packaging import version as package_version
 
 from opentelemetry import trace
+from opentelemetry.instrumentation._labeler import clear_labeler
 from opentelemetry.instrumentation._semconv import (
     HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
     OTEL_SEMCONV_STABILITY_OPT_IN,
@@ -103,12 +104,35 @@
     "http.server.request.duration": _server_duration_attrs_new,
 }
 
+_custom_attributes = ["custom_attr", "endpoint_type", "feature_flag"]
+_server_duration_attrs_old_with_custom = _server_duration_attrs_old.copy()
+_server_duration_attrs_old_with_custom.append("http.target")
+_server_duration_attrs_old_with_custom.extend(_custom_attributes)
+_server_duration_attrs_new_with_custom = _server_duration_attrs_new.copy()
+_server_duration_attrs_new_with_custom.append("http.route")
+_server_duration_attrs_new_with_custom.extend(_custom_attributes)
+
+_recommended_metrics_attrs_old_with_custom = {
+    "http.server.active_requests": _server_active_requests_count_attrs_old,
+    "http.server.duration": _server_duration_attrs_old_with_custom,
+}
+_recommended_metrics_attrs_new_with_custom = {
+    "http.server.active_requests": _server_active_requests_count_attrs_new,
+    "http.server.request.duration": _server_duration_attrs_new_with_custom,
+}
+_recommended_metrics_attrs_both_with_custom = {
+    "http.server.active_requests": _server_active_requests_count_attrs_both,
+    "http.server.duration": _server_duration_attrs_old_with_custom,
+    "http.server.request.duration": _server_duration_attrs_new_with_custom,
+}
+
 _parsed_falcon_version = package_version.parse(_falcon_version)
 
 
 class TestFalconBase(TestBase):
     def setUp(self):
         super().setUp()
+        clear_labeler()
 
         test_name = ""
         if hasattr(self, "_testMethodName"):
@@ -544,6 +568,38 @@ def test_falcon_metrics(self):
                             )
         self.assertTrue(number_data_point_seen and histogram_data_point_seen)
 
+    def test_falcon_metrics_custom_attributes(self):
+        self.client().simulate_get("/user_custom_attr/123")
+        self.client().simulate_get("/user_custom_attr/123")
+        self.client().simulate_get("/user_custom_attr/123")
+        metrics_list = self.memory_metrics_reader.get_metrics_data()
+        number_data_point_seen = False
+        histogram_data_point_seen = False
+
+        self.assertTrue(len(metrics_list.resource_metrics) != 0)
+        for resource_metric in metrics_list.resource_metrics:
+            self.assertTrue(len(resource_metric.scope_metrics) != 0)
+            for scope_metric in resource_metric.scope_metrics:
+                self.assertTrue(len(scope_metric.metrics) != 0)
+                for metric in scope_metric.metrics:
+                    self.assertIn(metric.name, _expected_metric_names)
+                    data_points = list(metric.data.data_points)
+                    self.assertEqual(len(data_points), 1)
+                    for point in data_points:
+                        if isinstance(point, HistogramDataPoint):
+                            self.assertEqual(point.count, 3)
+                            histogram_data_point_seen = True
+                        if isinstance(point, NumberDataPoint):
+                            number_data_point_seen = True
+                        for attr in point.attributes:
+                            self.assertIn(
+                                attr,
+                                _recommended_metrics_attrs_old_with_custom[
+                                    metric.name
+                                ],
+                            )
+        self.assertTrue(number_data_point_seen and histogram_data_point_seen)
+
     def test_falcon_metric_values_new_semconv(self):
         number_data_point_seen = False
         histogram_data_point_seen = False
@@ -580,6 +636,43 @@ def test_falcon_metric_values_new_semconv(self):
 
         self.assertTrue(number_data_point_seen and histogram_data_point_seen)
 
+    def test_falcon_metric_values_new_semconv_custom_attributes(self):
+        number_data_point_seen = False
+        histogram_data_point_seen = False
+
+        start = default_timer()
+        self.client().simulate_get("/user_custom_attr/123")
+        duration = max(default_timer() - start, 0)
+
+        metrics_list = self.memory_metrics_reader.get_metrics_data()
+        for resource_metric in metrics_list.resource_metrics:
+            for scope_metric in resource_metric.scope_metrics:
+                for metric in scope_metric.metrics:
+                    data_points = list(metric.data.data_points)
+                    self.assertEqual(len(data_points), 1)
+                    for point in data_points:
+                        if isinstance(point, HistogramDataPoint):
+                            self.assertEqual(point.count, 1)
+                            histogram_data_point_seen = True
+                            self.assertAlmostEqual(
+                                duration, point.sum, delta=10
+                            )
+                            self.assertEqual(
+                                point.explicit_bounds,
+                                HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
+                            )
+                        if isinstance(point, NumberDataPoint):
+                            self.assertEqual(point.value, 0)
+                            number_data_point_seen = True
+                        for attr in point.attributes:
+                            self.assertIn(
+                                attr,
+                                _recommended_metrics_attrs_new_with_custom[
+                                    metric.name
+                                ],
+                            )
+        self.assertTrue(number_data_point_seen and histogram_data_point_seen)
+
     def test_falcon_metric_values_both_semconv(self):
         number_data_point_seen = False
         histogram_data_point_seen = False
@@ -635,34 +728,59 @@ def test_falcon_metric_values_both_semconv(self):
                             )
         self.assertTrue(number_data_point_seen and histogram_data_point_seen)
 
-    def test_falcon_metric_values(self):
+    def test_falcon_metric_values_both_semconv_custom_attributes(self):
         number_data_point_seen = False
         histogram_data_point_seen = False
 
         start = default_timer()
-        self.client().simulate_get("/hello/756")
-        duration = max(round((default_timer() - start) * 1000), 0)
+        self.client().simulate_get("/user_custom_attr/123")
+        duration_s = default_timer() - start
 
         metrics_list = self.memory_metrics_reader.get_metrics_data()
+
+        # pylint: disable=too-many-nested-blocks
         for resource_metric in metrics_list.resource_metrics:
             for scope_metric in resource_metric.scope_metrics:
                 for metric in scope_metric.metrics:
+                    if metric.unit == "ms":
+                        self.assertEqual(metric.name, "http.server.duration")
+                    elif metric.unit == "s":
+                        self.assertEqual(
+                            metric.name, "http.server.request.duration"
+                        )
+                    else:
+                        self.assertEqual(
+                            metric.name, "http.server.active_requests"
+                        )
                     data_points = list(metric.data.data_points)
                     self.assertEqual(len(data_points), 1)
-                    for point in list(metric.data.data_points):
+                    for point in data_points:
                         if isinstance(point, HistogramDataPoint):
                             self.assertEqual(point.count, 1)
+                            if metric.unit == "ms":
+                                self.assertAlmostEqual(
+                                    max(round(duration_s * 1000), 0),
+                                    point.sum,
+                                    delta=10,
+                                )
+                            elif metric.unit == "s":
+                                self.assertAlmostEqual(
+                                    max(duration_s, 0), point.sum, delta=10
+                                )
+                                self.assertEqual(
+                                    point.explicit_bounds,
+                                    HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
+                                )
                             histogram_data_point_seen = True
-                            self.assertAlmostEqual(
-                                duration, point.sum, delta=10
-                            )
                         if isinstance(point, NumberDataPoint):
                             self.assertEqual(point.value, 0)
                             number_data_point_seen = True
                         for attr in point.attributes:
                             self.assertIn(
                                 attr,
-                                _recommended_metrics_attrs_old[metric.name],
+                                _recommended_metrics_attrs_both_with_custom[
+                                    metric.name
+                                ],
                             )
 
         self.assertTrue(number_data_point_seen and histogram_data_point_seen)