Mv example to docstring; lint

Author: tammy-baylis-swi

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

@@ -13,11 +13,64 @@
 # limitations under the License.
 
 """
-Labeler that supports per-request custom attribute addition to web framework
-instrumentor-originating OpenTelemetry metrics.
+OpenTelemetry Labeler
+=====================
+
+The labeler utility provides a way to add custom attributes to metrics generated by OpenTelemetry instrumentors. This supports enriching metrics with context-specific information available only after HTTP requests are received, at their origin rather than requiring downstream processing or additional metric calculations.
 
 This was inspired by OpenTelemetry Go's net/http instrumentation Labeler
 https://github.com/open-telemetry/opentelemetry-go-contrib/pull/306
+
+Usage
+-----
+
+The labeler works within the context of an instrumented request or operation. Use ``get_labeler()`` to obtain a labeler instance for the current context, then add attributes using the ``add()`` or ``add_attributes()`` methods.
+
+Example with Flask
+------------------
+
+Here's an example showing how to use the labeler with Flask instrumentation:
+
+.. 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("/healthcheck")
+    def healthcheck():
+        # Get the labeler for the current request
+        labeler = get_labeler()
+
+        labeler.add_attributes(
+            {
+                "endpoint_type": "healthcheck",
+                "internal_request": True,
+            }
+        )
+        return "OK"
+
+    @app.route("/user/<user_id>")
+    def user_profile(user_id):
+        labeler = get_labeler()
+
+        # Can add individual attributes or multiple at once
+        labeler.add("user_id", user_id)
+        labeler.add_attributes(
+            {
+                "has_premium": user_id in ["123", "456"],
+                "experiment_group": "control",
+                "feature_enabled": True,
+                "user_segment": "active",
+            }
+        )
+
+        return f"Got user profile for {user_id}"
+
+The labeler also works with auto-instrumentation and those instrumentors that have implemented custom attributes support for metrics.
 """
 
 from opentelemetry.instrumentation._labeler._internal import (

opentelemetry-instrumentation/src/opentelemetry/instrumentation/_labeler/_internal/__init__.py

@@ -24,11 +24,7 @@
 
 class Labeler:
     """
-    Labeler can be used by instrumented code or distro to add custom attributes
-    to the metrics recorded by those OpenTelemetry instrumentations reading it.
-
-    Labeler accumulates custom attributes for OpenTelemetry metrics for the
-    current request in context.
+    Stores custom attributes for the current request in context.
 
     This feature is experimental and unstable.
     """
@@ -142,13 +138,11 @@ def enhance_metric_attributes(
     max_attr_value_length: int = 100,
 ) -> Dict[str, Any]:
     """
-    This function combines base_attributes with custom attributes
-    from the current labeler.
-
-    Custom attributes are skipped if they would override base_attributes,
-    exceed max_custom_attrs number, or are not simple types (str, int, float,
-    bool). If custom attributes have string values exceeding the
-    max_attr_value_length, then they are truncated.
+    Combines base_attributes with custom attributes from the current labeler,
+    returning a new dictionary of attributes. Custom attributes are skipped
+    if they would override base_attributes, exceed max_custom_attrs number,
+    or are not simple types (str, int, float, bool). If custom attributes
+    have string values exceeding the max_attr_value_length, then they are truncated.
 
     Args:
         base_attributes: The base attributes for the metric

opentelemetry-instrumentation/src/opentelemetry/instrumentation/_labeler/example.py

@@ -82,8 +82,11 @@ def test_thread_safety(self):
         num_operations = 100
 
         def worker(thread_id):
-            for i in range(num_operations):
-                labeler.add(f"thread_{thread_id}_key_{i}", f"value_{i}")
+            for i_operation in range(num_operations):
+                labeler.add(
+                    f"thread_{thread_id}_key_{i_operation}",
+                    f"value_{i_operation}",
+                )
 
         # Start multiple threads
         threads = []
@@ -158,11 +161,14 @@ def context_worker(context_id, results):
         results = {}
 
         # Run in different contextvars contexts
-        for i in range(3):
+        for i_operation in range(3):
             ctx = contextvars.copy_context()
-            ctx.run(context_worker, i, results)
+            ctx.run(context_worker, i_operation, results)
 
         # Each context should have its own labeler with its own values
-        for i in range(3):
-            expected = {"context_id": i, "value": f"context_{i}"}
-            self.assertEqual(results[i], expected)
+        for i_operation in range(3):
+            expected = {
+                "context_id": i_operation,
+                "value": f"context_{i_operation}",
+            }
+            self.assertEqual(results[i_operation], expected)