Flask enrich_metric_attributes from Labeler if set

Author: tammy-baylis-swi

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

@@ -250,6 +250,51 @@ def response_hook(span: Span, status: str, response_headers: List):
 | ``controller``    | Flask controller/endpoint name.                    | ``controller='home_view'``             |
 +-------------------+----------------------------------------------------+----------------------------------------+
 
+Custom Metrics Attributes using Labeler
+***************************************
+The Flask instrumentation reads from a labeler utility that supports adding custom
+attributes to HTTP server metrics at emit time, including:
+
+- Active requests counter (``http.server.active_requests``)
+- Duration histogram (``http.server.duration``)
+- Request duration histogram (``http.server.request.duration``)
+
+The custom attributes are stored in the current OpenTelemetry context and are
+typically request-scoped for instrumented Flask handlers. In normal application
+flow, context detach at request teardown prevents these attributes from leaking
+to later requests. Application code typically should not call ``clear_labeler``;
+use it primarily for test isolation or manual context-lifecycle management. The
+instrumentor does not overwrite base attributes that exist at the same keys as
+any custom attributes.
+
+
+.. code-block:: python
+
+    from flask import Flask
+
+    from opentelemetry.instrumentation._labeler import get_labeler
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
+
+    app = Flask(__name__)
+    FlaskInstrumentor().instrument_app(app)
+
+    @app.route("/users/<user_id>/")
+    def user_profile(user_id):
+        # Get the labeler for the current request
+        labeler = get_labeler()
+
+        # Add custom attributes to Flask 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"
+        })
+
+        return f"User profile for {user_id}"
+
 API
 ---
 """
@@ -266,6 +311,10 @@ def response_hook(span: Span, status: str, response_headers: List):
 
 import opentelemetry.instrumentation.wsgi as otel_wsgi
 from opentelemetry import context, trace
+from opentelemetry.instrumentation._labeler import (
+    enrich_metric_attributes,
+    get_labeler_attributes,
+)
 from opentelemetry.instrumentation._semconv import (
     HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
     _get_schema_url,
@@ -312,6 +361,7 @@ def response_hook(span: Span, status: str, response_headers: List):
 _ENVIRON_ACTIVATION_KEY = "opentelemetry-flask.activation_key"
 _ENVIRON_REQCTX_REF_KEY = "opentelemetry-flask.reqctx_ref_key"
 _ENVIRON_TOKEN = "opentelemetry-flask.token"
+_ENVIRON_LABELER_ATTRIBUTES_KEY = "opentelemetry-flask.labeler_attributes"
 
 _excluded_urls_from_env = get_excluded_urls("FLASK")
 
@@ -351,6 +401,7 @@ def _rewrapped_app(
     duration_histogram_new=None,
 ):
     # pylint: disable=too-many-statements
+    # pylint: disable=too-many-locals
     def _wrapped_app(wrapped_app_environ, start_response):
         # We want to measure the time for route matching, etc.
         # In theory, we could start the span here and use
@@ -367,6 +418,9 @@ def _wrapped_app(wrapped_app_environ, start_response):
                 sem_conv_opt_in_mode,
             )
         )
+        active_requests_count_attrs = enrich_metric_attributes(
+            active_requests_count_attrs
+        )
 
         active_requests_counter.add(1, active_requests_count_attrs)
         request_route = None
@@ -437,6 +491,15 @@ def _start_response(status, response_headers, *args, **kwargs):
                 if request_route:
                     # http.target to be included in old semantic conventions
                     duration_attrs_old[HTTP_TARGET] = str(request_route)
+                duration_attrs_old = enrich_metric_attributes(
+                    duration_attrs_old
+                )
+                labeler_metric_attributes = wrapped_app_environ.get(
+                    _ENVIRON_LABELER_ATTRIBUTES_KEY, {}
+                )
+                for key, value in labeler_metric_attributes.items():
+                    if key not in duration_attrs_old:
+                        duration_attrs_old[key] = value
                 duration_histogram_old.record(
                     max(round(duration_s * 1000), 0),
                     duration_attrs_old,
@@ -450,12 +513,32 @@ def _start_response(status, response_headers, *args, **kwargs):
                 if request_route:
                     duration_attrs_new[HTTP_ROUTE] = str(request_route)
 
+                duration_attrs_new = enrich_metric_attributes(
+                    duration_attrs_new
+                )
+                labeler_metric_attributes = wrapped_app_environ.get(
+                    _ENVIRON_LABELER_ATTRIBUTES_KEY, {}
+                )
+                for key, value in labeler_metric_attributes.items():
+                    if key not in duration_attrs_new:
+                        duration_attrs_new[key] = value
+
                 duration_histogram_new.record(
                     max(duration_s, 0),
                     duration_attrs_new,
                     context=metrics_context,
                 )
 
+        active_requests_count_attrs = enrich_metric_attributes(
+            active_requests_count_attrs
+        )
+        labeler_metric_attributes = wrapped_app_environ.get(
+            _ENVIRON_LABELER_ATTRIBUTES_KEY, {}
+        )
+        for key, value in labeler_metric_attributes.items():
+            if key not in active_requests_count_attrs:
+                active_requests_count_attrs[key] = value
+
         active_requests_counter.add(-1, active_requests_count_attrs)
         return result
 
@@ -561,6 +644,9 @@ def _teardown_request(exc):
 
         activation = flask.request.environ.get(_ENVIRON_ACTIVATION_KEY)
         token = flask.request.environ.get(_ENVIRON_TOKEN)
+        flask.request.environ[_ENVIRON_LABELER_ATTRIBUTES_KEY] = dict(
+            get_labeler_attributes()
+        )
 
         original_reqctx_ref = flask.request.environ.get(
             _ENVIRON_REQCTX_REF_KEY

instrumentation/opentelemetry-instrumentation-flask/tests/test_programmatic.py

@@ -18,7 +18,9 @@
 
 from flask import Flask, request
 
+import opentelemetry.instrumentation.flask as otel_flask
 from opentelemetry import trace
+from opentelemetry.instrumentation._labeler import clear_labeler, get_labeler
 from opentelemetry.instrumentation._semconv import (
     HTTP_DURATION_HISTOGRAM_BUCKETS_NEW,
     OTEL_SEMCONV_STABILITY_OPT_IN,
@@ -153,6 +155,7 @@ def expected_attributes_new(override_attributes):
 class TestProgrammatic(InstrumentationTest, WsgiTestBase):
     def setUp(self):
         super().setUp()
+        clear_labeler()
 
         test_name = ""
         if hasattr(self, "_testMethodName"):
@@ -180,6 +183,18 @@ def setUp(self):
         self.exclude_patch.start()
 
         self.app = Flask(__name__)
+
+        @self.app.route("/test_labeler")
+        def test_labeler_route():
+            labeler = get_labeler()
+            labeler.add("custom_attr", "test_value")
+            labeler.add("http.method", "POST")
+            return "OK"
+
+        @self.app.route("/no_labeler")
+        def test_no_labeler_route():
+            return "No labeler"
+
         FlaskInstrumentor().instrument_app(self.app)
 
         self._common_initialization()
@@ -521,6 +536,122 @@ def test_flask_metrics(self):
                     )
         self.assertTrue(number_data_point_seen and histogram_data_point_seen)
 
+    def test_flask_metrics_custom_attributes_skip_override(self):
+        self.client.get("/test_labeler")
+        metrics = self.get_sorted_metrics(SCOPE)
+        active_requests_point_seen = False
+        histogram_point_seen = False
+
+        for metric in metrics:
+            if metric.name == "http.server.active_requests":
+                data_points = list(metric.data.data_points)
+                for point in data_points:
+                    self.assertIsInstance(point, NumberDataPoint)
+                    if point.attributes.get("custom_attr") != "test_value":
+                        continue
+                    self.assertEqual(point.attributes[HTTP_METHOD], "GET")
+                    active_requests_point_seen = True
+                continue
+
+            if metric.name != "http.server.duration":
+                continue
+            data_points = list(metric.data.data_points)
+            self.assertEqual(len(data_points), 1)
+            point = data_points[0]
+            self.assertIsInstance(point, HistogramDataPoint)
+            self.assertEqual(point.attributes[HTTP_METHOD], "GET")
+            self.assertEqual(point.attributes["custom_attr"], "test_value")
+            histogram_point_seen = True
+
+        self.assertTrue(active_requests_point_seen)
+        self.assertTrue(histogram_point_seen)
+
+    def test_flask_metrics_active_requests_custom_attributes_new_semconv(self):
+        self.client.get("/test_labeler")
+        metrics = self.get_sorted_metrics(SCOPE)
+        active_requests_point_seen = False
+
+        for metric in metrics:
+            if metric.name != "http.server.active_requests":
+                continue
+
+            data_points = list(metric.data.data_points)
+            for point in data_points:
+                self.assertIsInstance(point, NumberDataPoint)
+                if point.attributes.get("custom_attr") != "test_value":
+                    continue
+                self.assertEqual(point.attributes[HTTP_REQUEST_METHOD], "GET")
+                active_requests_point_seen = True
+
+        self.assertTrue(active_requests_point_seen)
+
+    def test_flask_active_requests_attrs_use_enrich_old_semconv(self):
+        with patch(
+            "opentelemetry.instrumentation.flask.enrich_metric_attributes",
+            wraps=otel_flask.enrich_metric_attributes,
+        ) as mock_enrich:
+            self.client.get("/hello/123")
+
+        enriched_active_attrs_seen = False
+        for call in mock_enrich.call_args_list:
+            if not call.args:
+                continue
+            attrs = call.args[0]
+            if HTTP_METHOD in attrs and HTTP_STATUS_CODE not in attrs:
+                enriched_active_attrs_seen = True
+                break
+
+        self.assertTrue(enriched_active_attrs_seen)
+
+    def test_flask_active_requests_attrs_use_enrich_new_semconv(self):
+        with patch(
+            "opentelemetry.instrumentation.flask.enrich_metric_attributes",
+            wraps=otel_flask.enrich_metric_attributes,
+        ) as mock_enrich:
+            self.client.get("/hello/123")
+
+        enriched_active_attrs_seen = False
+        for call in mock_enrich.call_args_list:
+            if not call.args:
+                continue
+            attrs = call.args[0]
+            if (
+                HTTP_REQUEST_METHOD in attrs
+                and HTTP_RESPONSE_STATUS_CODE not in attrs
+            ):
+                enriched_active_attrs_seen = True
+                break
+
+        self.assertTrue(enriched_active_attrs_seen)
+
+    def test_flask_metrics_no_labeler(self):
+        self.client.get("/test_labeler")
+        self.client.get("/no_labeler")
+
+        metrics = self.get_sorted_metrics(SCOPE)
+        labeler_attrs = None
+        no_labeler_attrs = None
+
+        for metric in metrics:
+            if metric.name != "http.server.duration":
+                continue
+
+            data_points = list(metric.data.data_points)
+            self.assertEqual(len(data_points), 2)
+
+            for point in data_points:
+                self.assertIsInstance(point, HistogramDataPoint)
+                attrs = point.attributes
+                if attrs.get(HTTP_TARGET) == "/test_labeler":
+                    labeler_attrs = attrs
+                elif attrs.get(HTTP_TARGET) == "/no_labeler":
+                    no_labeler_attrs = attrs
+
+        self.assertIsNotNone(labeler_attrs)
+        self.assertIsNotNone(no_labeler_attrs)
+        self.assertEqual(labeler_attrs["custom_attr"], "test_value")
+        self.assertNotIn("custom_attr", no_labeler_attrs)
+
     def test_flask_metrics_new_semconv(self):
         start = default_timer()
         self.client.get("/hello/123")